kiro-telegram-bot 1.6.0 → 1.7.1

package/src/app/auth-service.ts

@@ -0,0 +1,325 @@
+/**
+ * Kiro authentication control for /reauth: `kiro-cli logout` then an interactive
+ * `kiro-cli login --use-device-flow`. The device flow prints a verification URL
+ * + code to stdout (no browser redirect on the bot host), which we stream back
+ * to Telegram so the user can complete it on their own device.
+ */
+import { execFile, spawn } from "node:child_process";
+import { rm } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { createLogger } from "../logger.js";
+
+const run = promisify(execFile);
+const log = createLogger("auth");
+
+// Strip ANSI colour/cursor escapes so the Telegram transcript stays readable.
+// eslint-disable-next-line no-control-regex
+const ANSI_RE = /\x1b\[[0-9;?]*[ -/]*[@-~]/g;
+
+export interface LoginResult {
+  ok: boolean;
+  code: number | null;
+  /** True when the login was aborted via the supplied AbortSignal. */
+  cancelled?: boolean;
+  /** Human-readable failure reason, when known (shown in the chat). */
+  error?: string;
+}
+
+export interface LoginOptions {
+  /** Extra CLI flags (e.g. `--license pro`). `--use-device-flow` is added if absent. */
+  extraArgs?: string[];
+  /** Receives decoded stdout/stderr chunks as they arrive. */
+  onOutput: (text: string) => void;
+  /** Overall timeout before the login process is killed (default 5 min). */
+  timeoutMs?: number;
+  /** Abort to cancel the in-flight login — kills the process (Cancel button). */
+  signal?: AbortSignal;
+}
+
+export interface IdcLoginOptions {
+  /** IAM Identity Center start URL (e.g. https://my-org.awsapps.com/start). */
+  startUrl: string;
+  /** AWS region of the Identity Center (e.g. us-east-1). */
+  region: string;
+  /** Receives decoded output chunks as they arrive. */
+  onOutput: (text: string) => void;
+  /** Overall timeout before the login process is killed (default 5 min). */
+  timeoutMs?: number;
+  /** Abort to cancel the in-flight login — kills the process (Cancel button). */
+  signal?: AbortSignal;
+}
+
+/** Minimal shape of the optional `node-pty` module we rely on. */
+interface IPty {
+  onData(cb: (data: string) => void): void;
+  onExit(cb: (e: { exitCode: number; signal?: number }) => void): void;
+  write(data: string): void;
+  kill(signal?: string): void;
+}
+interface PtyModule {
+  spawn(
+    file: string,
+    args: string[],
+    options: { name?: string; cols?: number; rows?: number; cwd?: string; env?: NodeJS.ProcessEnv },
+  ): IPty;
+}
+
+export class AuthService {
+  constructor(private readonly kiroCliPath: string) {}
+
+  /** Run `kiro-cli logout` (non-interactive). */
+  async logout(): Promise<{ ok: boolean; out: string }> {
+    try {
+      const { stdout, stderr } = await run(this.kiroCliPath, ["logout"], {
+        timeout: 30_000,
+        encoding: "utf-8",
+      });
+      return { ok: true, out: clean(`${stdout}${stderr}`) };
+    } catch (e) {
+      const err = e as { stdout?: string; stderr?: string; message?: string };
+      const out = clean(`${err.stdout ?? ""}${err.stderr ?? ""}`) || err.message || "logout failed";
+      return { ok: false, out };
+    }
+  }
+
+  /**
+   * Best-effort removal of Kiro's cached auth token (`~/.aws/sso/cache/
+   * kiro-auth-token.json`) — the file that carries the logged-in identity
+   * (accessToken + refreshToken). Removing it after `logout` guarantees the
+   * next `login` performs a genuine device-flow authentication instead of
+   * silently reusing the previous account's cached/refreshable token.
+   *
+   * Surgical and safe: it touches ONLY Kiro's own token file, never the shared,
+   * account-agnostic OIDC client registrations, and is a no-op if absent.
+   */
+  async clearTokenCache(): Promise<boolean> {
+    const path = join(homedir(), ".aws", "sso", "cache", "kiro-auth-token.json");
+    try {
+      await rm(path, { force: true });
+      log.info(`cleared cached auth token (${path})`);
+      return true;
+    } catch (e) {
+      log.debug("clearTokenCache failed:", (e as Error).message);
+      return false;
+    }
+  }
+
+  /**
+   * to `onOutput` as it arrives (so the device code/URL reaches the user fast).
+   * Resolves when the process exits, the timeout fires, or the signal aborts.
+   */
+  login(opts: LoginOptions): Promise<LoginResult> {
+    const { extraArgs = [], onOutput, timeoutMs = 300_000, signal } = opts;
+    return new Promise<LoginResult>((resolve) => {
+      if (signal?.aborted) {
+        resolve({ ok: false, code: null, cancelled: true });
+        return;
+      }
+      const args = ["login"];
+      if (!extraArgs.includes("--use-device-flow")) args.push("--use-device-flow");
+      args.push(...extraArgs);
+      log.info(`spawning login: ${this.kiroCliPath} ${args.join(" ")}`);
+
+      let proc;
+      try {
+        // stdin ignored: any interactive prompt gets EOF rather than hanging.
+        proc = spawn(this.kiroCliPath, args, { stdio: ["ignore", "pipe", "pipe"] });
+      } catch (e) {
+        onOutput(`error: ${(e as Error).message}`);
+        resolve({ ok: false, code: null });
+        return;
+      }
+
+      let cancelled = false;
+      let settled = false;
+      let hardKill: NodeJS.Timeout | undefined;
+
+      const onAbort = (): void => {
+        cancelled = true;
+        try {
+          proc.kill();
+        } catch {
+          /* ignore */
+        }
+        // Escalate if the CLI ignores the polite signal.
+        hardKill = setTimeout(() => {
+          try {
+            proc.kill("SIGKILL");
+          } catch {
+            /* ignore */
+          }
+        }, 2000);
+      };
+
+      const finish = (r: LoginResult): void => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        if (hardKill) clearTimeout(hardKill);
+        signal?.removeEventListener("abort", onAbort);
+        resolve(r);
+      };
+
+      const feed = (b: Buffer): void => {
+        const t = clean(b.toString("utf-8"));
+        if (t) onOutput(t);
+      };
+      proc.stdout.on("data", feed);
+      proc.stderr.on("data", feed);
+
+      const timer = setTimeout(() => {
+        onOutput("\n\u23F1\uFE0F Timed out waiting for login to complete.");
+        try {
+          proc.kill();
+        } catch {
+          /* ignore */
+        }
+      }, timeoutMs);
+
+      signal?.addEventListener("abort", onAbort, { once: true });
+
+      proc.on("error", (e: Error) => {
+        onOutput(`error: ${e.message}`);
+        finish({ ok: false, code: null, cancelled });
+      });
+      proc.on("exit", (code: number | null) => {
+        finish({ ok: code === 0 && !cancelled, code, cancelled });
+      });
+    });
+  }
+
+  /**
+   * IAM Identity Center (Pro) login. Unlike the Builder ID device flow, this
+   * CLI path is *interactive*: it always prompts ("Enter Start URL", "Enter
+   * Region", and — when the account has several — an Identity Center profile
+   * picker) and refuses to run without a real terminal. So we drive it inside a
+   * pseudo-terminal (the optional `node-pty` module), answering each prompt with
+   * the start URL / region the user supplied and accepting the default profile.
+   * The device verification URL + code still stream out via `onOutput`.
+   */
+  loginIdc(opts: IdcLoginOptions): Promise<LoginResult> {
+    const { startUrl, region, onOutput, timeoutMs = 300_000, signal } = opts;
+    return new Promise<LoginResult>((resolve) => {
+      if (signal?.aborted) {
+        resolve({ ok: false, code: null, cancelled: true });
+        return;
+      }
+      void (async () => {
+        // Load the optional native PTY lazily via a variable specifier so a
+        // missing module is a graceful runtime error, not an install/type break.
+        let pty: PtyModule;
+        try {
+          const specifier = "@homebridge/node-pty-prebuilt-multiarch";
+          const mod = (await import(specifier)) as unknown as PtyModule & { default?: PtyModule };
+          pty = typeof mod.spawn === "function" ? mod : (mod.default as PtyModule);
+          if (!pty || typeof pty.spawn !== "function") throw new Error("invalid pty module");
+        } catch {
+          resolve({
+            ok: false,
+            code: null,
+            error:
+              "IAM Identity Center login needs the PTY module. Run `npm install` in the bot folder, then try again.",
+          });
+          return;
+        }
+
+        // Pass the start URL + region as flags so the interactive prompts come
+        // PREFILLED — we then just press Enter to accept them. Typing the values
+        // ourselves makes the terminal echo them, which doubles the captured
+        // input (e.g. "us-east-1us-east-1" → bad OIDC endpoint). Q_FAKE_IS_REMOTE
+        // forces the CLI to PRINT the verification URL instead of opening a
+        // browser on the bot host, so it streams to Telegram.
+        const args = [
+          "login",
+          "--license",
+          "pro",
+          "--identity-provider",
+          startUrl,
+          "--region",
+          region,
+          "--use-device-flow",
+        ];
+        log.info(`spawning IDC login (pty): ${this.kiroCliPath} ${args.join(" ")}`);
+
+        let term: IPty;
+        try {
+          term = pty.spawn(this.kiroCliPath, args, {
+            name: "xterm-color",
+            cols: 120,
+            rows: 30,
+            env: { ...process.env, Q_FAKE_IS_REMOTE: "1" },
+          });
+        } catch (e) {
+          resolve({ ok: false, code: null, error: (e as Error).message });
+          return;
+        }
+
+        let buf = "";
+        let sentUrl = false;
+        let sentRegion = false;
+        let sentProfile = false;
+        let cancelled = false;
+        let settled = false;
+
+        const onAbort = (): void => {
+          cancelled = true;
+          try {
+            term.kill();
+          } catch {
+            /* ignore */
+          }
+        };
+
+        const finish = (r: LoginResult): void => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timer);
+          signal?.removeEventListener("abort", onAbort);
+          try {
+            term.kill();
+          } catch {
+            /* ignore */
+          }
+          resolve(r);
+        };
+
+        const timer = setTimeout(() => {
+          onOutput("\n\u23F1\uFE0F Timed out waiting for login to complete.");
+          try {
+            term.kill();
+          } catch {
+            /* ignore */
+          }
+        }, timeoutMs);
+
+        signal?.addEventListener("abort", onAbort, { once: true });
+
+        term.onData((d: string) => {
+          const t = clean(d);
+          if (t) onOutput(t);
+          buf += t;
+          // Each prompt is PREFILLED (from the flags); just press Enter to accept
+          // it. We answer each exactly once, in order.
+          if (!sentUrl && /start url/i.test(buf)) {
+            sentUrl = true;
+            term.write("\r");
+          } else if (sentUrl && !sentRegion && /enter region/i.test(buf)) {
+            sentRegion = true;
+            term.write("\r");
+          } else if (sentRegion && !sentProfile && /select an iam identity center profile/i.test(buf)) {
+            sentProfile = true;
+            term.write("\r"); // accept the default (first) profile
+          }
+        });
+
+        term.onExit(({ exitCode }) => finish({ ok: exitCode === 0 && !cancelled, code: exitCode, cancelled }));
+      })();
+    });
+  }
+}
+
+function clean(s: string): string {
+  return s.replace(ANSI_RE, "").replace(/\r/g, "");
+}

package/src/bot/bot.ts

@@ -30,6 +30,8 @@ import { registerPhotos } from "./handlers/photo.js";
 import { registerProjects } from "./handlers/projects.js";
 import { registerRunning, switchAndShow } from "./handlers/running.js";
 import { registerSessions } from "./handlers/sessions.js";
+import { registerSessionKill } from "./handlers/session-kill.js";
+import { registerReauth } from "./handlers/auth.js";
 import { registerSystem } from "./handlers/system.js";
 import { registerTasks, registerWizardInput } from "./handlers/tasks.js";
 import { registerUsage } from "./handlers/usage.js";
@@ -146,9 +148,11 @@ export async function createBot(cfg: AppConfig, acp: AcpClient): Promise<BotBund
   registerControl(bot, deps);
   registerProjects(bot, deps);
   registerSessions(bot, deps);
+  registerSessionKill(bot, deps);
   registerRunning(bot, deps);
   registerHistory(bot, deps);
   registerSystem(bot, deps);
+  registerReauth(bot, deps);
   registerUsage(bot, deps);
   registerKill(bot, deps);
   registerMcp(bot, deps);

package/src/bot/chat-controller.ts

@@ -20,6 +20,8 @@ export interface RunningSession {
   busy: boolean;
   foreground: boolean;
   unread: number;
+  /** Latest task-completion % (0–100) for this session, if known. */
+  progress?: number;
 }
 
 export interface SwitchResult {
@@ -71,6 +73,7 @@ export class ChatController {
       busy: rt.isBusy,
       foreground: rt.isForeground,
       unread: this.unreadCount(rt),
+      progress: rt.taskProgress,
     }));
   }
 
@@ -188,6 +191,13 @@ export class ChatController {
     return this.runtimes.length;
   }
 
+  /** Latest task-progress % for a controlled session id, if this chat runs it. */
+  progressFor(sessionId?: string): number | undefined {
+    if (!sessionId) return undefined;
+    this.ensureRestored();
+    return this.runtimes.find((r) => r.sessionId === sessionId)?.taskProgress;
+  }
+
   findBySession(sessionId: string): boolean {
     return this.runtimes.some((r) => r.sessionId === sessionId);
   }

package/src/bot/commands.ts

@@ -23,6 +23,7 @@ export const COMMANDS: { command: string; description: string }[] = [
   { command: "unwatch", description: "Stop following a live session" },
   { command: "model", description: "Switch model: /model <id>" },
   { command: "restart", description: "Restart the Kiro agent" },
+  { command: "reauth", description: "Log out & log in to Kiro (device flow)" },
   { command: "help", description: "Show help" },
 ];
 

package/src/bot/handlers/auth.ts

@@ -0,0 +1,89 @@
+/**
+ * /reauth — re-authenticate Kiro. Instead of always running one provider's
+ * device flow, it first shows a login-method picker (Builder ID, Google,
+ * GitHub, IAM Identity Center). The chosen method drives a logout → device-flow
+ * login → agent restart on a single, self-animated status message. Inline
+ * buttons drive the flow:
+ *   • Builder ID / Google / GitHub / IAM Identity Center — pick how to log in
+ *   • Cancel        — abort the picker or the in-flight logout/login
+ *   • Back / Change method — return to the picker
+ *   • Retry         — re-run the last method on the same message
+ *   • Restart agent — retry just the agent restart after a restart failure
+ *
+ * Power users can still skip the picker by passing flags directly, e.g.
+ * `/reauth --license pro --identity-provider <url> --region <region>`.
+ *
+ * Guarded: refused while a prompt is in flight (logging out would break the
+ * running turn) and serialised per chat so two runs can't overlap.
+ */
+import type { Bot } from "grammy";
+import type { BotDeps } from "../deps.js";
+import { type LoginMethod, ReauthController } from "../reauth-controller.js";
+
+export function registerReauth(bot: Bot, deps: BotDeps): void {
+  const controller = new ReauthController(deps.api, deps.acp, deps.cfg.kiroCliPath, () => deps.usage.account());
+
+  // IDC start-URL/region text capture. Registered before the catch-all message
+  // handler so the reply feeds the reauth flow instead of becoming a prompt.
+  bot.on("message:text", async (ctx, next) => {
+    const chatId = ctx.chat.id;
+    if (!controller.awaitingIdcInput(chatId)) return next();
+    const text = ctx.message.text;
+    if (text.startsWith("/")) return next(); // let a command through; picker stays
+    await controller.submitIdcInput(chatId, text);
+  });
+
+  bot.command("reauth", async (ctx) => {
+    if (controller.isBusy(ctx.chat.id)) {
+      await ctx.reply("\u{1F510} A re-authentication is already in progress.");
+      return;
+    }
+    const extra = (ctx.match?.toString() ?? "").trim().split(/\s+/).filter(Boolean);
+    // Explicit flags skip the picker (advanced / scripted use); otherwise ask.
+    if (extra.length > 0) await controller.begin(ctx.chat.id, extra);
+    else await controller.chooseMethod(ctx.chat.id);
+  });
+
+  bot.callbackQuery(/^reauth:method:(builder|google|github|idc)$/, async (ctx) => {
+    await ctx.answerCallbackQuery();
+    const chatId = ctx.chat?.id;
+    const messageId = ctx.callbackQuery.message?.message_id;
+    if (chatId !== undefined && messageId !== undefined) {
+      await controller.pickMethod(chatId, messageId, ctx.match![1] as LoginMethod);
+    }
+  });
+
+  bot.callbackQuery("reauth:choose-back", async (ctx) => {
+    await ctx.answerCallbackQuery();
+    const chatId = ctx.chat?.id;
+    const messageId = ctx.callbackQuery.message?.message_id;
+    if (chatId !== undefined && messageId !== undefined) await controller.chooseMethod(chatId, messageId);
+  });
+
+  bot.callbackQuery("reauth:choose-cancel", async (ctx) => {
+    await ctx.answerCallbackQuery({ text: "Cancelled" });
+    const chatId = ctx.chat?.id;
+    const messageId = ctx.callbackQuery.message?.message_id;
+    if (chatId !== undefined && messageId !== undefined) await controller.cancelChoice(chatId, messageId);
+  });
+
+  bot.callbackQuery("reauth:cancel", async (ctx) => {
+    const chatId = ctx.chat?.id;
+    const ok = chatId !== undefined && controller.cancel(chatId);
+    await ctx.answerCallbackQuery({ text: ok ? "Cancelling\u2026" : "Nothing to cancel" });
+  });
+
+  bot.callbackQuery("reauth:retry", async (ctx) => {
+    await ctx.answerCallbackQuery({ text: "Retrying\u2026" });
+    const chatId = ctx.chat?.id;
+    const messageId = ctx.callbackQuery.message?.message_id;
+    if (chatId !== undefined && messageId !== undefined) await controller.retry(chatId, messageId);
+  });
+
+  bot.callbackQuery("reauth:restart", async (ctx) => {
+    await ctx.answerCallbackQuery({ text: "Restarting agent\u2026" });
+    const chatId = ctx.chat?.id;
+    const messageId = ctx.callbackQuery.message?.message_id;
+    if (chatId !== undefined && messageId !== undefined) await controller.restartAgent(chatId, messageId);
+  });
+}

package/src/bot/handlers/kill.ts

@@ -3,14 +3,11 @@
  * holding a live session lock), excluding the bot's own agent process. Guarded
  * by an inline confirmation since it kills processes.
  */
-import { execFileSync } from "node:child_process";
 import { type Bot, type Context, InlineKeyboard } from "grammy";
-import { createLogger } from "../../logger.js";
+import { killPid } from "../../sessions/process.js";
 import type { SessionMeta } from "../../sessions/types.js";
 import type { BotDeps } from "../deps.js";
 
-const log = createLogger("killall");
-
 function targets(deps: BotDeps): SessionMeta[] {
   const self = deps.acp.pid;
   return deps.store.listActive().filter((s) => s.lockPid && s.lockPid !== self);
@@ -55,17 +52,3 @@ export function registerKill(bot: Bot, deps: BotDeps): void {
     await ctx.editMessageText(`\u{1F6D1} Killed ${killed} of ${active.length} active session(s).`).catch(() => {});
   });
 }
-
-function killPid(pid: number): boolean {
-  try {
-    if (process.platform === "win32") {
-      execFileSync("taskkill", ["/F", "/T", "/PID", String(pid)], { stdio: "ignore" });
-    } else {
-      process.kill(pid, "SIGKILL");
-    }
-    return true;
-  } catch (e) {
-    log.debug(`kill ${pid} failed:`, (e as Error).message);
-    return false;
-  }
-}

package/src/bot/handlers/running.ts

@@ -8,6 +8,7 @@ import type { RunningSession, SwitchResult } from "../chat-controller.js";
 import type { BotDeps } from "../deps.js";
 import type { HistoryEntry } from "../../sessions/types.js";
 import { jsonlMtimeMs, readFirstPrompt } from "../../sessions/history.js";
+import { progressBar } from "../../render/progress.js";
 import { refreshMenu } from "../menu/refresh.js";
 import { sendMarkdownDoc } from "../telegram-io.js";
 
@@ -71,6 +72,7 @@ function buildRunningCard(s: RunningSession, deps: BotDeps, now: number): { text
     prompt ? `\u{1F4AC} \u201C${trunc(prompt, 120)}\u201D` : "\u{1F4AC} (no messages yet)",
     `\u{1F552} ${meta.join(" \u00B7 ")}`,
   ];
+  if (s.progress !== undefined) lines.push(`\u{1F4C8} ${progressBar(s.progress)}`);
   if (s.sessionId) lines.push(`\u{1F194} ${s.sessionId.slice(0, 8)}`);
 
   const kb = new InlineKeyboard();

package/src/bot/handlers/session-card.ts

@@ -8,11 +8,20 @@
  */
 import { InlineKeyboard } from "grammy";
 import { basename } from "node:path";
+import { progressBar } from "../../render/progress.js";
 import type { SessionMeta } from "../../sessions/types.js";
 
 export interface SessionCardExtras {
   /** Context-usage %, when the session is loaded in the current ACP process. */
   contextPct?: number;
+  /**
+   * PID of the bot's own `kiro-cli acp` process. A session locked by this PID
+   * powers the bot itself, so its card omits the Kill button (killing it would
+   * take the bot down). Other live sessions get a 🛑 Kill button.
+   */
+  selfPid?: number;
+  /** Latest task-completion % (0–100) for this session, if this chat runs it. */
+  progress?: number;
 }
 
 export interface SessionCard {
@@ -31,6 +40,7 @@ export function buildSessionCard(m: SessionMeta, extra: SessionCardExtras = {}):
   lines.push(`\u{1F552} updated ${relTime(m.updatedAt)} \u00B7 created ${relTime(m.createdAt)}`);
   const ctx = typeof extra.contextPct === "number" ? ` \u00B7 \u{1F9E0} ctx ${Math.round(extra.contextPct)}%` : "";
   lines.push(`\u{1F4CA} ${state} \u00B7 \u{1F4DC} history ${humanSize(m.historyBytes)}${ctx}`);
+  if (typeof extra.progress === "number") lines.push(`\u{1F4C8} ${progressBar(extra.progress)}`);
   lines.push(`\u{1F194} ${m.sessionId.slice(0, 8)}`);
 
   const connect = m.active ? "\u{1F374} Continue (fork)" : "\u{1F517} Resume";
@@ -39,6 +49,12 @@ export function buildSessionCard(m: SessionMeta, extra: SessionCardExtras = {}):
     .text("\u{1F4DC} History", `hist:${m.sessionId}`)
     .text("\u{1F4E1} Watch", `watch:${m.sessionId}`);
 
+  // A live session running in another process can be terminated by PID. The
+  // bot's own agent (selfPid) is never offered — killing it would stop the bot.
+  if (m.active && typeof m.lockPid === "number" && m.lockPid !== extra.selfPid) {
+    keyboard.row().text(`\u{1F6D1} Kill \u00B7 pid ${m.lockPid}`, `killsess:${m.sessionId}`);
+  }
+
   return { text: lines.join("\n"), keyboard };
 }
 

package/src/bot/handlers/session-kill.ts

@@ -0,0 +1,95 @@
+/**
+ * Per-session kill — terminate the OS process holding a live session's `.lock`
+ * straight from its card in /sessions or /active.
+ *
+ * Flow (callback data, UUID-keyed so it survives bot restarts):
+ *   killsess:<id>          a tap on the card's 🛑 Kill button → ask to confirm
+ *   killsess:do:<id>       confirmed → kill the lockPid, report the outcome
+ *   killsess:cancel:<id>   abort → restore the card's normal buttons
+ *
+ * Guards: the bot's own agent (acp.pid) is never killable here (its card never
+ * shows the button, and the handlers re-check), and state is re-read from disk
+ * at every step so a session that already stopped can't be "killed" twice.
+ */
+import { type Bot, type Context, InlineKeyboard } from "grammy";
+import { killPid } from "../../sessions/process.js";
+import type { SessionMeta } from "../../sessions/types.js";
+import type { BotDeps } from "../deps.js";
+import { buildSessionCard } from "./session-card.js";
+
+const UUID = "([0-9a-fA-F-]{36})";
+
+/** Rebuild the standard card keyboard for the freshest on-disk session state. */
+function cardKeyboard(deps: BotDeps, meta: SessionMeta): InlineKeyboard {
+  const contextPct = deps.acp.metadataFor(meta.sessionId)?.contextUsagePercentage;
+  return buildSessionCard(meta, { contextPct, selfPid: deps.acp.pid }).keyboard;
+}
+
+/** Re-read the session and decide whether its PID may be killed right now. */
+function killable(
+  deps: BotDeps,
+  id: string,
+): { ok: true; meta: SessionMeta; pid: number } | { ok: false; meta?: SessionMeta; reason: string } {
+  const meta = deps.store.get(id);
+  if (!meta) return { ok: false, reason: "Session not found." };
+  if (!meta.active || typeof meta.lockPid !== "number") {
+    return { ok: false, meta, reason: "Session is no longer running." };
+  }
+  if (meta.lockPid === deps.acp.pid) {
+    return { ok: false, meta, reason: "That's the bot's own agent — can't kill it." };
+  }
+  return { ok: true, meta, pid: meta.lockPid };
+}
+
+export function registerSessionKill(bot: Bot, deps: BotDeps): void {
+  // Step 1 — ask to confirm. Swap the card's buttons for a Kill/Cancel row.
+  bot.callbackQuery(new RegExp(`^killsess:${UUID}$`), async (ctx) => {
+    const id = ctx.match![1]!;
+    const check = killable(deps, id);
+    if (!check.ok) {
+      await ctx.answerCallbackQuery({ text: check.reason });
+      // The button is stale (session stopped); refresh it to the normal card.
+      if (check.meta) await ctx.editMessageReplyMarkup({ reply_markup: cardKeyboard(deps, check.meta) }).catch(() => {});
+      return;
+    }
+    await ctx.answerCallbackQuery();
+    const kb = new InlineKeyboard()
+      .text(`\u{1F6D1} Kill pid ${check.pid}`, `killsess:do:${id}`)
+      .text("\u21A9 Cancel", `killsess:cancel:${id}`);
+    await ctx.editMessageReplyMarkup({ reply_markup: kb }).catch(() => {});
+  });
+
+  // Step 2a — confirmed. Re-validate (it may have died meanwhile), then kill.
+  bot.callbackQuery(new RegExp(`^killsess:do:${UUID}$`), async (ctx) => {
+    const id = ctx.match![1]!;
+    const check = killable(deps, id);
+    if (!check.ok) {
+      await ctx.answerCallbackQuery({ text: check.reason });
+      await appendStatus(ctx, check.reason);
+      return;
+    }
+    const title = check.meta.title;
+    const ok = killPid(check.pid);
+    await ctx.answerCallbackQuery({ text: ok ? "Killed" : "Kill failed" });
+    const note = ok
+      ? `\u{1F6D1} Killed ${title} (pid ${check.pid}).`
+      : `\u26A0\uFE0F Could not kill pid ${check.pid} (already gone, or not permitted).`;
+    await appendStatus(ctx, note);
+  });
+
+  // Step 2b — cancelled. Put the card's normal buttons back.
+  bot.callbackQuery(new RegExp(`^killsess:cancel:${UUID}$`), async (ctx) => {
+    const id = ctx.match![1]!;
+    await ctx.answerCallbackQuery({ text: "Cancelled" });
+    const meta = deps.store.get(id);
+    if (meta) await ctx.editMessageReplyMarkup({ reply_markup: cardKeyboard(deps, meta) }).catch(() => {});
+    else await ctx.editMessageReplyMarkup().catch(() => {});
+  });
+}
+
+/** Append a one-line status under the card and drop its keyboard. */
+async function appendStatus(ctx: Context, note: string): Promise<void> {
+  const body = ctx.callbackQuery?.message?.text;
+  const text = body ? `${body}\n\n${note}` : note;
+  await ctx.editMessageText(text).catch(() => {});
+}

package/src/bot/handlers/sessions.ts

@@ -52,7 +52,8 @@ async function renderSessionPage(ctx: Context, deps: BotDeps, page: number): Pro
 
   for (const m of slice) {
     const contextPct = deps.acp.metadataFor(m.sessionId)?.contextUsagePercentage;
-    const { text, keyboard } = buildSessionCard(m, { contextPct });
+    const progress = deps.registry.controller(ctx.chat!.id).progressFor(m.sessionId);
+    const { text, keyboard } = buildSessionCard(m, { contextPct, selfPid: deps.acp.pid, progress });
     await deps.ephemeral.reply(ctx, text, { reply_markup: keyboard });
   }