tokenmaxxing 0.17.0 → 0.19.0

package/src/entries/statusline.ts

@@ -1,14 +1,18 @@
 // Native statusLine. Reads Claude's statusLine stdin, tees the rate-limit data
 // to usage.json (write-on-change, O(ms)), then renders ONE line:
-//   worktree name (linked worktrees only), model (effort), ctx used,
-//   +added/-removed, then quota as USED percent (bold, severity-colored)
-//   glued after its time-to-reset: "◆ F26 2h5 1d38  ◇ F67 2d40  ◇ 2 full"
-//   ("2h5" = resets in 2h, 5 used) - the active account's windows after a
-//   green ◆ (per-model by initial first, "F?" when the cap applies but is
-//   unmeasured, then session/5h, then week), then each parked account's week
-//   after a cyan ◇, in swap-preference order so the first usable ◇ is where
-//   the next swap lands. Adjacent untouched (or unsampled) parked accounts
-//   collapse into one counted token. Blocks are joined by TWO spaces, tokens
+//   worktree name (linked worktrees only), model name painted by context fill
+//   (effort in parens), +added/-removed, then quota as COLOR (user decisions
+//   2026-07-18): each window is its time-to-reset painted on a continuous
+//   green->yellow->red ramp by used% - "◆ 𝒇 2h 1d  ◇ 2d  ◇ full" - the
+//   active account's windows after a green ◆ (per-model by bare initial
+//   first, fable as 𝒇, other families uppercased; "𝒇?" unpainted when the
+//   cap applies but is unmeasured, then session/5h, then week), then EVERY
+//   parked account's week after its own cyan ◇ (red ✗ if needs-reauth),
+//   sorted by earliest upcoming reset (needs-reauth last). A window with no
+//   upcoming reset renders "0" (empty again); measured usage with an unknown
+//   reset clock renders a painted "?". With color disabled the numeric format
+//   returns ("2h5" = resets in 2h, 5 used; "ctx 42"): without color a drained
+//   window must not look fresh. Blocks are joined by TWO spaces, tokens
 //   within a block by one. Per-model resets are omitted (they match the
 //   weekly reset).
 // Must NEVER break the status line: render what parses, skip what doesn't.
@@ -17,14 +21,13 @@ import { sortBy } from "es-toolkit";
 import { z } from "zod";
 import { readOAuthAccount } from "../lib/claudejson.ts";
 import { loadAccounts, loadConfig, loadLastSwapAt, loadModelUsage, writeUsage } from "../lib/state.ts";
-import { familyTokens, gatedFamilies, matchedFamily, parseStatusLineStdin, parseStatusLineModel } from "../lib/usage.ts";
-import { effectiveBars, isExhausted, swapPreference, weeklyExpiry } from "../lib/picker.ts";
+import { familyTokens, matchedFamily, parseStatusLineStdin, parseStatusLineModel } from "../lib/usage.ts";
+import { earliestReset, weeklyExpiry } from "../lib/picker.ts";
 import { worktreeName } from "../lib/worktree.ts";
-import { fmtResetShort, makeColors } from "../cli/render.ts";
+import { fmtResetShort, makeColors, makeUsagePaint } from "../cli/render.ts";
 import {
   AccountsIndexSchema,
   StatusLineStdinSchema,
-  ThresholdsSchema,
   UsageWindowSchema,
   type Account,
   type UsageState,
@@ -42,15 +45,16 @@ const RenderCtxSchema = z.object({
   perModel: z.record(z.string(), UsageWindowSchema),
   /** families (lowercased) whose per-model weekly cap gates a switch. */
   switchModels: z.array(z.string()),
-  thresholds: ThresholdsSchema,
   /** linked-worktree basename, null in a main checkout. */
   worktree: z.string().nullable(),
   now: z.number(),
   color: z.boolean(),
+  /** terminal advertises 24-bit color (COLORTERM); false steps the ramp to the 256-color cube. */
+  truecolor: z.boolean(),
 });
 export type RenderCtx = z.infer<typeof RenderCtxSchema>;
 
-async function readStdin(): Promise<string> {
+export async function readStdin(): Promise<string> {
   const chunks: Uint8Array[] = [];
   for await (const c of Bun.stdin.stream()) chunks.push(c);
   return Buffer.concat(chunks).toString("utf8");
@@ -59,8 +63,7 @@ async function readStdin(): Promise<string> {
 /** Pure renderer: statusLine stdin + tokenmaxxing state → the emitted line. */
 export function renderStatusline(stdinObj: unknown, ctx: RenderCtx): string {
   const col = makeColors(ctx.color);
-  const severity = (u: number) => (u >= 95 ? col.red : u >= 75 ? col.yellow : col.green);
-  const gauge = (u: number) => col.bold(severity(u)(`${Math.round(u)}`));
+  const paint = makeUsagePaint({ enabled: ctx.color, truecolor: ctx.truecolor });
   // Used quota in a window; one whose reset has passed is empty again.
   const used = (w: UsageWindow) => (w.resetsAt != null && w.resetsAt <= ctx.now ? 0 : w.usedPercentage);
   const reset = (epochMs: number | null) => fmtResetShort(epochMs, ctx.now);
@@ -71,29 +74,43 @@ export function renderStatusline(stdinObj: unknown, ctx: RenderCtx): string {
   // ---- info block: worktree, model, ctx, diff
   const info: string[] = [];
   if (ctx.worktree != null) info.push(ctx.worktree);
+  // The model name carries the context-fill color (user rule 2026-07-18, no
+  // ctx token); colorless mode keeps the numeric ctx token instead.
   const modelName = d?.model?.display_name ?? d?.model?.id;
+  const ctxUsed = d?.context_window?.used_percentage;
   if (modelName) {
     const effort = d?.effort?.level;
-    info.push(col.bold(modelName) + (effort ? ` (${effort})` : ""));
+    const body = ctxUsed != null ? col.bold(paint(ctxUsed)(modelName)) : col.bold(modelName);
+    info.push(body + (effort ? ` (${effort})` : ""));
   }
-  const ctxUsed = d?.context_window?.used_percentage;
-  if (ctxUsed != null) info.push(`ctx ${gauge(ctxUsed)}`);
+  if (!ctx.color && ctxUsed != null) info.push(`ctx ${Math.round(ctxUsed)}`);
   const added = d?.cost?.total_lines_added ?? 0;
   const removed = d?.cost?.total_lines_removed ?? 0;
   // -removed stays unpainted: red means quota alarm and nothing else.
   if (added > 0 || removed > 0) info.push(`${col.green(`+${added}`)}/-${removed}`);
 
   // ---- active account block
-  const seg = (label: string, w: UsageWindow, resetAt: number | null) =>
-    `${label}${reset(resetAt)}${gauge(used(w))}`;
+  // A window token: color carries the used%, the text is the reset countdown
+  // (or the bare per-model initial - per-model resets are omitted). "0" = no
+  // upcoming reset (the window is empty again); a painted "?" = measured usage
+  // whose reset clock is unknown. Colorless mode glues the number back on.
+  const seg = (label: string, w: UsageWindow, resetAt: number | null) => {
+    const u = used(w);
+    if (!ctx.color) return `${label}${reset(resetAt)}${Math.round(u)}`;
+    const body = label !== "" ? label : reset(resetAt);
+    return col.bold(paint(u)(body !== "" ? body : u > 0 ? "?" : "0"));
+  };
+  // Per-model initial: fable renders 𝒇 (user rule 2026-07-18), family-matched
+  // as always; other families keep their uppercased first letter.
+  const initial = (name: string) => (familyTokens(name).includes("fable") ? "𝒇" : name.slice(0, 1).toUpperCase());
   const wins = parseStatusLineStdin(stdinObj);
   const windows: string[] = [];
   // A capacity-constrained model whose cap is unmeasured must not look safe.
   const family = matchedFamily(parseStatusLineModel(stdinObj), ctx.switchModels);
   if (family && !Object.keys(ctx.perModel).some((k) => familyTokens(k).includes(family))) {
-    windows.push(`${family[0]!.toUpperCase()}?`);
+    windows.push(`${initial(family)}?`);
   }
-  for (const [name, w] of Object.entries(ctx.perModel)) windows.push(seg(name.slice(0, 1), w, null));
+  for (const [name, w] of Object.entries(ctx.perModel)) windows.push(seg(initial(name), w, null));
   if (wins) {
     windows.push(seg("", wins.fiveHour, wins.fiveHour.resetsAt));
     windows.push(seg("", wins.sevenDay, wins.sevenDay.resetsAt));
@@ -105,49 +122,31 @@ export function renderStatusline(stdinObj: unknown, ctx: RenderCtx): string {
         ? `${col.green("◆")} ?`
         : "";
 
-  // ---- parked accounts, in swap order: the first usable ◇ is the next target
-  const pickCtx = {
-    now: ctx.now,
-    thresholds: ctx.thresholds,
-    currentAccountUuid: ctx.accounts.activeAccountUuid,
-    switchFamilies: gatedFamilies(parseStatusLineModel(stdinObj), ctx.switchModels),
-  };
+  // ---- parked accounts, earliest upcoming reset first (needs-reauth last)
   const parked = sortBy(
     ctx.accounts.accounts.filter((a) => a.accountUuid !== ctx.accounts.activeAccountUuid),
-    [(a) => (a.needsReauth || isExhausted(a, pickCtx) ? 1 : 0), ...swapPreference(ctx.now)],
+    [(a) => (a.needsReauth ? 1 : 0), (a) => earliestReset(a, ctx.now)],
   );
-  const poolSeg = (a: Account): { kind: "full" | "unknown" | "other"; text: string } => {
+  // Every parked account renders its own marker (user rule 2026-07-18: the
+  // old counted collapse "◇ 3 full" hid the pool size and read as confusing).
+  const poolSeg = (a: Account): string => {
     const marker = a.needsReauth ? col.red("✗") : col.cyan("◇");
-    const mergeable = !a.needsReauth;
-
     const week = a.lastUsage?.sevenDay;
-    if (week == null) return { kind: mergeable ? "unknown" : "other", text: `${marker} ?` };
+    if (week == null) return `${marker} ?`;
     const weekUsed = used(week);
-    if (Math.round(weekUsed) <= 0) return { kind: mergeable ? "full" : "other", text: `${marker} ${col.green("full")}` };
+    if (Math.round(weekUsed) <= 0) return `${marker} ${paint(0)("full")}`;
 
     const parts: string[] = [];
     // A per-model weekly cap with more used than the aggregate is the binding constraint - surface it.
     for (const [name, w] of Object.entries(a.lastPerModel ?? {})) {
-      if (used(w) > weekUsed) parts.push(seg(name.slice(0, 1), w, null));
+      if (used(w) > weekUsed) parts.push(seg(initial(name), w, null));
     }
     const expiry = weeklyExpiry(a, ctx.now);
     parts.push(seg("", week, Number.isFinite(expiry) ? expiry : null));
-    return { kind: "other", text: `${marker} ${parts.join(" ")}` };
+    return `${marker} ${parts.join(" ")}`;
   };
 
-  // Adjacent identical bare tokens collapse into one counted token ("◇ 3 full").
-  const pool: string[] = [];
-  const segs = parked.map(poolSeg);
-  for (let i = 0; i < segs.length; ) {
-    const s = segs[i]!;
-    let j = i + 1;
-    while (s.kind !== "other" && j < segs.length && segs[j]!.kind === s.kind) j++;
-    if (j - i >= 2) pool.push(`${col.cyan("◇")} ${j - i} ${s.kind === "full" ? col.green("full") : "?"}`);
-    else pool.push(s.text);
-    i = j;
-  }
-
-  return [info.join(" "), active, ...pool].filter((l) => l !== "").join("  ");
+  return [info.join(" "), active, ...parked.map(poolSeg)].filter((l) => l !== "").join("  ");
 }
 
 export async function runStatusline(): Promise<number> {
@@ -178,14 +177,15 @@ export async function runStatusline(): Promise<number> {
   const modelUsage = loadModelUsage();
   const stdin = StatusLineStdinSchema.safeParse(obj);
   const dir = stdin.success ? (stdin.data.workspace?.current_dir ?? stdin.data.workspace?.project_dir ?? null) : null;
+  const colorterm = z.string().optional().parse(process.env.COLORTERM);
   const ctx: RenderCtx = {
     accounts: loadAccounts(),
     perModel: modelUsage && modelUsage.org === org ? modelUsage.perModel : {},
     switchModels: cfg.policy.switchModels,
-    thresholds: effectiveBars(cfg),
     worktree: dir == null ? null : worktreeName(dir),
     now,
     color: !process.env.NO_COLOR,
+    truecolor: colorterm != null && (colorterm.includes("truecolor") || colorterm.includes("24bit")),
   };
   process.stdout.write(renderStatusline(obj, ctx) + "\n");
   return 0;

package/src/entries/subagentstatusline.ts

@@ -0,0 +1,78 @@
+// Renders claude's subagentStatusLine: one {id, content} JSON line per active
+// subagent task, so the agents panel shows each subagent's model, effort, and
+// ctx fill the way the main statusline shows the session's (user ask
+// 2026-07-18). This per-row panel surface is the only place subagent info can
+// appear: the main statusLine command never learns which subagent the UI is
+// viewing (verified against the 2.1.214 bundle). Row shape mirrors the main
+// info block, info first so claude's end-truncation eats the label instead:
+//   "fable (high)  <task label>" - the family name painted by the task's
+//   context fill (colorless mode keeps a numeric ctx token).
+// A task we emit nothing for keeps claude's default row (emitting empty
+// content would HIDE it). Must NEVER break the panel: render what parses,
+// skip what doesn't.
+
+import { z } from "zod";
+import { makeColors, makeUsagePaint } from "../cli/render.ts";
+import { readStdin } from "./statusline.ts";
+import { SubagentStatusLineStdinSchema } from "../lib/types.ts";
+
+const RowCtxSchema = z.object({ color: z.boolean(), truecolor: z.boolean() });
+export type RowCtx = z.infer<typeof RowCtxSchema>;
+
+/** "claude-fable-5" -> "fable" (lowercase family, matching the chart-label
+ *  convention); an id without the claude- prefix passes through whole. */
+function modelFamily(id: string): string {
+  const [head, family] = id.split("-");
+  return head === "claude" && family ? family : id;
+}
+
+/** Pure renderer: subagentStatusLine stdin -> {id, content} JSON lines. */
+export function renderSubagentRows(stdinObj: unknown, ctx: RowCtx): string[] {
+  const parsed = SubagentStatusLineStdinSchema.safeParse(stdinObj);
+  if (!parsed.success) return [];
+  const col = makeColors(ctx.color);
+  const paint = makeUsagePaint({ enabled: ctx.color, truecolor: ctx.truecolor });
+
+  const rows: string[] = [];
+  for (const t of parsed.data.tasks ?? []) {
+    if (t.id == null) continue;
+    const pct =
+      t.tokenCount != null && t.contextWindowSize != null && t.contextWindowSize > 0
+        ? Math.round((t.tokenCount / t.contextWindowSize) * 100)
+        : null;
+    const info: string[] = [];
+    // The model name carries the task's context-fill color (same rule as the
+    // main line); colorless mode keeps the numeric ctx token instead.
+    if (t.model != null) {
+      const family = modelFamily(t.model);
+      const body = pct != null ? col.bold(paint(pct)(family)) : col.bold(family);
+      info.push(body + (t.effort ? ` (${t.effort})` : ""));
+    }
+    if (!ctx.color && pct != null) info.push(`ctx ${pct}`);
+
+    const label = t.label ?? t.description ?? t.name;
+    const parts: string[] = [];
+    if (info.length > 0) parts.push(info.join(" "));
+    if (label != null && label !== "") parts.push(label);
+    if (parts.length === 0) continue;
+    rows.push(JSON.stringify({ id: t.id, content: parts.join("  ") }));
+  }
+  return rows;
+}
+
+export async function runSubagentStatusline(): Promise<number> {
+  const raw = await readStdin();
+  let obj: unknown = null;
+  try {
+    obj = JSON.parse(raw);
+  } catch {
+    // malformed stdin - emit nothing, claude keeps its default rows
+  }
+  const colorterm = z.string().optional().parse(process.env.COLORTERM);
+  const rows = renderSubagentRows(obj, {
+    color: !process.env.NO_COLOR,
+    truecolor: colorterm != null && (colorterm.includes("truecolor") || colorterm.includes("24bit")),
+  });
+  if (rows.length > 0) process.stdout.write(rows.join("\n") + "\n");
+  return 0;
+}

package/src/lib/decide.ts

@@ -111,7 +111,7 @@ function usageFresh(u: UsageState | null, org: string | null, ttl: number, now:
  * are absent, org-drifted, or older than the poll TTL. ONE probe carries all
  * three limit kinds, so a success refreshes BOTH files; anything less leaves a
  * headless box (no rendering statusLine to tee) evaluating frozen or
- * org-mismatched values forever - the 2026-07-12 stella blindness. The
+ * org-mismatched values forever - the 2026-07-12 ARM-box blindness. The
  * refreshed usage carries model: null (whatever session stamped the old model
  * may be gone), which gates every configured family. model-usage.json's ts also
  * stamps FAILED attempts, so a busy live token cannot cause a probe storm

package/src/lib/paths.ts

@@ -35,6 +35,13 @@ export const paths = {
   /** linux only: parked credential .json files (0700 dir, 0600 files). */
   credsDir: join(TM_HOME, "creds"),
 
+  /** `xx serve` slack bridge: tokens + channel->repo links (0600: holds the
+   *  xoxb-/xapp- tokens), per-thread claude session records, and the git
+   *  worktrees threads run in. */
+  slackJson: join(TM_HOME, "slack.json"),
+  slackThreadsDir: join(TM_HOME, "slack-threads"),
+  slackWorktreesDir: join(TM_HOME, "slack-worktrees"),
+
   /** ~/.claude.json - holds the active `oauthAccount` identity object. */
   claudeJson: env("TOKENMAXXING_CLAUDE_JSON", join(HOME, ".claude.json")),
   /** ~/.claude/settings.json - user-owned; we merge three entries into it. */

package/src/lib/picker.ts

@@ -98,6 +98,16 @@ export function weeklyExpiry(a: Account, now: number): number {
   return nextWeeklyReset(a.lastUsage?.sevenDay.resetsAt ?? null, now) ?? Number.POSITIVE_INFINITY;
 }
 
+/** Soonest upcoming reset among the account's cached windows: the 5h session
+ *  reset if still ahead, else the extrapolated weekly expiry; Infinity with no
+ *  known reset anchor (sorts last). Display order for `status` and the
+ *  statusLine pool (user decision 2026-07-18) - deliberately decoupled from
+ *  swapPreference, which keeps ranking actual swaps. */
+export function earliestReset(a: Account, now: number): number {
+  const fiveHour = a.lastUsage?.fiveHour.resetsAt;
+  return Math.min(fiveHour != null && fiveHour > now ? fiveHour : Number.POSITIVE_INFINITY, weeklyExpiry(a, now));
+}
+
 /** How far behind its own weekly pace the account is, measured forward: the
  *  burn rate (percent per ms) its remaining weekly quota must be consumed at
  *  to beat the reset that forfeits it. A backward-looking used/expected ratio
@@ -116,8 +126,7 @@ export function pacePressure(a: Account, now: number): number {
 
 /** The switch preference: furthest behind its own weekly pace first (highest
  *  pacePressure), tiebreak soonest weekly expiry then lowest 7-day usage.
- *  Shared with the statusLine pool ordering so the display order IS the
- *  swap order. */
+ *  Ranks swaps only; display surfaces order by earliestReset instead. */
 export const swapPreference = (now: number) => [
   (a: Account) => -pacePressure(a, now),
   (a: Account) => weeklyExpiry(a, now),

package/src/lib/settings.ts

@@ -1,7 +1,8 @@
-// Idempotent merge of tokenmaxxing's three entries into the user-owned
-// ~/.claude/settings.json: our statusLine, a Stop hook, a SessionStart hook.
-// Hooks APPEND to existing arrays; the statusLine slot is ours outright -
-// tokenmaxxing renders it natively, so any other statusLine command is replaced.
+// Idempotent merge of tokenmaxxing's entries into the user-owned
+// ~/.claude/settings.json: our statusLine + subagentStatusLine, a Stop hook,
+// a SessionStart hook. Hooks APPEND to existing arrays; the statusLine slots
+// are ours outright - tokenmaxxing renders them natively, so any other
+// statusLine command is replaced.
 
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
@@ -19,6 +20,7 @@ const HookGroupSchema = z.looseObject({ matcher: z.string().optional(), hooks: z
 const StatusLineSchema = z.looseObject({ type: z.string(), command: z.string() });
 const SettingsSchema = z.looseObject({
   statusLine: StatusLineSchema.optional(),
+  subagentStatusLine: StatusLineSchema.optional(),
   hooks: z.record(z.string(), z.array(HookGroupSchema)).optional(),
 });
 type Settings = z.infer<typeof SettingsSchema>;
@@ -26,6 +28,7 @@ type HookGroup = z.infer<typeof HookGroupSchema>;
 
 const SUBCMD = {
   statusline: "__statusline",
+  subagentStatusline: "__subagent-statusline",
   stop: "__stop-hook",
   sessionStart: "__session-start",
 } as const;
@@ -44,6 +47,7 @@ export function isOurCommand(cmd: string | undefined): boolean {
   if (!cmd) return false;
   return (
     cmd.includes(SUBCMD.statusline) ||
+    cmd.includes(SUBCMD.subagentStatusline) ||
     cmd.includes(SUBCMD.stop) ||
     cmd.includes(SUBCMD.sessionStart) ||
     // also match the installed bin path even if the subcommand text changes
@@ -70,29 +74,35 @@ function removeHook(s: Settings, event: string, sub: string): void {
   if (s.hooks![event]!.length === 0) delete s.hooks![event];
 }
 
-/** Install the three entries: take the statusLine slot, append our hooks. */
+/** Install the entries: take both statusLine slots, append our hooks. */
 export function installSettings(): void {
   const s = readSettings();
   s.statusLine = {
     type: "command",
     command: `${JSON.stringify(installedBin())} ${SUBCMD.statusline}`,
   };
+  s.subagentStatusLine = {
+    type: "command",
+    command: `${JSON.stringify(installedBin())} ${SUBCMD.subagentStatusline}`,
+  };
   appendHook(s, "Stop", SUBCMD.stop);
   appendHook(s, "SessionStart", SUBCMD.sessionStart);
   writeSettings(s);
 }
 
-/** Remove our three entries. The statusLine slot is deleted only if it is ours. */
+/** Remove our entries. The statusLine slots are deleted only if they are ours. */
 export function uninstallSettings(): void {
   const s = readSettings();
   removeHook(s, "Stop", SUBCMD.stop);
   removeHook(s, "SessionStart", SUBCMD.sessionStart);
   if (s.statusLine && isOurCommand(s.statusLine.command)) delete s.statusLine;
+  if (s.subagentStatusLine && isOurCommand(s.subagentStatusLine.command)) delete s.subagentStatusLine;
   writeSettings(s);
 }
 
 const SettingsCheckSchema = z.object({
   statusLineOk: z.boolean(),
+  subagentStatusLineOk: z.boolean(),
   stopOk: z.boolean(),
   sessionStartOk: z.boolean(),
 });
@@ -104,6 +114,7 @@ export function checkSettings(): SettingsCheck {
     !!s.hooks?.[event]?.some((g) => g.hooks?.some((h) => h.command?.includes(sub)));
   return {
     statusLineOk: isOurCommand(s.statusLine?.command),
+    subagentStatusLineOk: isOurCommand(s.subagentStatusLine?.command),
     stopOk: has("Stop", SUBCMD.stop),
     sessionStartOk: has("SessionStart", SUBCMD.sessionStart),
   };

package/src/lib/slackbridge.ts

@@ -0,0 +1,180 @@
+// The Slack->claude relay. One claude turn per Slack message via the Agent SDK
+// (re-query with resume, never a persistent streaming query: the SDK subprocess
+// reads credentials at spawn, so per-turn spawns are what let the pool decision
+// pick the freshest account at every boundary and let the daemon restart
+// without losing threads). Verified against @anthropic-ai/claude-agent-sdk
+// 0.3.214 and code.claude.com/docs 2026-07-18; both change monthly.
+
+import { existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { query } from "@anthropic-ai/claude-agent-sdk";
+import type { StreamChunk } from "chat";
+import { ensureBestAccount, pooledOptions, stopHookCheck } from "../sdk.ts";
+import { paths } from "./paths.ts";
+import { threadKey, type SlackLink } from "./slackstate.ts";
+import { agentEventChunks, newStreamMapState, SegmentBreakSchema } from "./slackstream.ts";
+import { log } from "./log.ts";
+
+export const TurnOutcomeSchema = z.object({
+  sessionId: z.string().nullable(),
+  failed: z.boolean(),
+});
+export type TurnOutcome = z.infer<typeof TurnOutcomeSchema>;
+
+const SegmentChunkSchema = z.union([z.string(), z.custom<StreamChunk>()]);
+type SegmentChunk = z.infer<typeof SegmentChunkSchema>;
+
+/** A hand-pushed async iterable: relayThread feeds one of these per Slack
+ *  message segment while thread.post concurrently drains it. */
+function pushableStream(): {
+  iterable: AsyncIterable<SegmentChunk>;
+  push: (chunk: SegmentChunk) => void;
+  end: () => void;
+} {
+  const queue: SegmentChunk[] = [];
+  let done = false;
+  let notify: (() => void) | null = null;
+  return {
+    push(chunk) {
+      queue.push(chunk);
+      notify?.();
+    },
+    end() {
+      done = true;
+      notify?.();
+    },
+    iterable: {
+      async *[Symbol.asyncIterator]() {
+        while (true) {
+          for (let next = queue.shift(); next !== undefined; next = queue.shift()) yield next;
+          if (done) return;
+          await new Promise<void>((resolve) => {
+            notify = resolve;
+          });
+          notify = null;
+        }
+      },
+    },
+  };
+}
+
+/** Run one git command against a repo; throws with trimmed stderr on failure. */
+function git(repo: string, args: string[]): string {
+  const r = Bun.spawnSync(["git", "-C", repo, ...args], { stdout: "pipe", stderr: "pipe" });
+  const stderr = new TextDecoder().decode(r.stderr).trim();
+  if (r.exitCode !== 0) throw new Error(`git ${args[0]} failed: ${stderr.slice(0, 200)}`);
+  return new TextDecoder().decode(r.stdout).trim();
+}
+
+/**
+ * The stable cwd a thread's turns run in. Worktree mode (default) creates
+ * `slack-worktrees/<threadKey>` on branch `tm-slack-<threadKey>` cut from the
+ * repo's current HEAD, once; both survive daemon restarts because resume is
+ * cwd-keyed. Worktrees are never auto-deleted (they hold the thread's work):
+ * clean up with `git worktree remove` when done.
+ */
+export function ensureThreadCwd(input: { link: SlackLink; threadId: string }): string {
+  if (!input.link.worktree) return input.link.repo;
+  const key = threadKey(input.threadId);
+  const dir = join(paths.slackWorktreesDir, key);
+  if (existsSync(dir)) return dir;
+  mkdirSync(paths.slackWorktreesDir, { recursive: true });
+  const branch = `tm-slack-${key}`;
+  const branchExists = Bun.spawnSync(["git", "-C", input.link.repo, "rev-parse", "--verify", "--quiet", branch]).exitCode === 0;
+  // a crash between branch creation and worktree add leaves the branch behind;
+  // reattach instead of failing on -b collision.
+  if (branchExists) git(input.link.repo, ["worktree", "add", dir, branch]);
+  else git(input.link.repo, ["worktree", "add", dir, "-b", branch]);
+  log("serve.worktree_created", { dir, branch });
+  return dir;
+}
+
+/**
+ * One claude turn relayed into a Slack thread as a SEQUENCE of messages: reply
+ * text streams natively, thinking and tool calls stream as task_update cards
+ * (see slackstream.ts), and a segment_break (a tool starting after streamed
+ * text) closes the current Slack message and opens the next one, so a turn
+ * reads as separate messages around its tool runs (user ask 2026-07-18).
+ * Segments post strictly in order: the next opens only after the previous
+ * post resolves. Never throws: a failure posts a short diagnostic line and
+ * sets outcome.failed (the daemon must keep serving other threads). Error
+ * text is message-only - a raw error body could echo request material.
+ */
+export async function relayThread(input: {
+  cwd: string;
+  sessionId: string | null;
+  prompt: string;
+  link: SlackLink;
+  post: (m: AsyncIterable<SegmentChunk>) => Promise<unknown>;
+}): Promise<TurnOutcome> {
+  const outcome: TurnOutcome = { sessionId: input.sessionId, failed: false };
+  let segment: ReturnType<typeof pushableStream> | null = null;
+  let lastPost: Promise<unknown> = Promise.resolve();
+  let postedText = false;
+  const push = async (chunk: SegmentChunk) => {
+    let seg = segment;
+    if (!seg) {
+      await lastPost; // strict message order: previous segment fully posted first
+      seg = pushableStream();
+      segment = seg;
+      lastPost = input.post(seg.iterable).catch((e: unknown) => {
+        const detail = (e instanceof Error ? e.message : String(e)).slice(0, 300);
+        log("serve.post_error", { err: detail });
+      });
+    }
+    if (!postedText && !(chunk instanceof Object)) postedText = true;
+    seg.push(chunk);
+  };
+  const breakSegment = () => {
+    segment?.end();
+    segment = null;
+  };
+  try {
+    // the switch decision runs at the spawn boundary, same as the CLI hooks.
+    await ensureBestAccount();
+    const q = query({
+      prompt: input.prompt,
+      options: {
+        ...pooledOptions(),
+        cwd: input.cwd,
+        permissionMode: input.link.permissionMode,
+        // the SDK refuses bypassPermissions without this explicit opt-in.
+        ...(input.link.permissionMode === "bypassPermissions" ? { allowDangerouslySkipPermissions: true } : {}),
+        includePartialMessages: true,
+        // no one can answer an interactive question dialog through Slack;
+        // without the tool the model asks in prose and the user's thread
+        // reply becomes the next turn.
+        disallowedTools: ["AskUserQuestion"],
+        hooks: { Stop: [{ hooks: [stopHookCheck] }] },
+        ...(input.link.model ? { model: input.link.model } : {}),
+        ...(input.sessionId ? { resume: input.sessionId } : {}),
+      },
+    });
+    const mapState = newStreamMapState();
+    let result: string | null = null;
+    for await (const message of q) {
+      if (message.type === "system" && message.subtype === "init") outcome.sessionId = message.session_id;
+      if (message.type === "result") {
+        outcome.sessionId = message.session_id;
+        if (message.subtype === "success") result = message.result;
+        else outcome.failed = true;
+      }
+      for (const part of agentEventChunks({ state: mapState, message })) {
+        if (SegmentBreakSchema.safeParse(part).success) breakSegment();
+        else await push(SegmentChunkSchema.parse(part));
+      }
+    }
+    // a turn that produced no streamed text (tool-only turns) still reports.
+    if (!postedText && result) await push(result);
+    if (!postedText && !result && outcome.failed) await push("the turn ended without a result (limit or error) - trying again may help");
+  } catch (e) {
+    outcome.failed = true;
+    const detail = (e instanceof Error ? e.message : String(e)).slice(0, 300);
+    log("serve.turn_error", { err: detail });
+    await push(`tokenmaxxing: turn failed: ${detail}`);
+  }
+  breakSegment();
+  await lastPost;
+  return outcome;
+}