@sayknow-cli/coding-agent 0.3.7 → 0.3.9

package/src/notifications/lifecycle-commands.ts

@@ -15,10 +15,23 @@ import * as os from "node:os";
 import type { SessionCloseTarget, SessionCreateTarget, SessionLifecycleResponse, SessionResumeTarget } from "./index";
 
 export type LifecycleCommandVerb = "session_create" | "session_close" | "session_resume";
+function normalizeLifecycleCommandToken(
+	token: string,
+	ctx: { chatType?: string; botUsername?: string } = {},
+): string | undefined {
+	const at = token.indexOf("@");
+	const command = at === -1 ? token : token.slice(0, at);
+	if (!/^\/session_(create|close|resume|recent)\b/.test(command)) return undefined;
+	if (at === -1) return ctx.chatType === undefined || ctx.chatType === "private" ? command : undefined;
+
+	const botUsername = ctx.botUsername;
+	if (!botUsername || token.slice(at + 1).toLowerCase() !== botUsername.toLowerCase()) return undefined;
+	return command;
+}
 
 /** A parsed, validated lifecycle command (transport identity added by caller). */
 export type ParsedLifecycleCommand =
-	| { kind: "create"; target: SessionCreateTarget }
+	| { kind: "create"; target: SessionCreateTarget; modelPreset?: string }
 	| { kind: "close"; target: SessionCloseTarget }
 	| { kind: "resume"; target: SessionResumeTarget }
 	| { kind: "recent"; which: "create" | "resume" | "all" }
@@ -28,18 +41,49 @@ export type ParsedLifecycleCommand =
 
 const USAGE = [
 	"Session commands:",
-	"/session_create path <dir>",
-	"/session_create worktree <repo> <branch>",
-	"/session_create dir <newdir>",
+	"/session_create path <dir> [--mpreset <profile>]",
+	"/session_create worktree <repo> <branch> [--mpreset <profile>]",
+	"/session_create dir <newdir> [--mpreset <profile>]",
 	"/session_close <sessionId>",
 	"/session_resume <sessionId|prefix>",
 	"/session_recent [create|resume]",
 ].join("\n");
 
-/** True when the text begins a /session_* command (cheap pre-gate). */
-export function isLifecycleCommandText(text: string | undefined): boolean {
+/** True when the text begins with any /session_* token, regardless of addressability. */
+export function isLifecycleCommandLikeText(text: string | undefined): boolean {
+	if (!text) return false;
+	const [token] = text.trim().split(/\s+/, 1);
+	if (!token) return false;
+	const at = token.indexOf("@");
+	const command = at === -1 ? token : token.slice(0, at);
+	return /^\/session_(create|close|resume|recent)\b/.test(command);
+}
+
+/** True when the text begins an addressable /session_* command (cheap pre-gate). */
+export function isLifecycleCommandText(
+	text: string | undefined,
+	ctx: { chatType?: string; botUsername?: string } = {},
+): boolean {
 	if (!text) return false;
-	return /^\/session_(create|close|resume|recent)\b/.test(text.trim());
+	const [rawCommand] = text.trim().split(/\s+/, 1);
+	return normalizeLifecycleCommandToken(rawCommand ?? "", ctx) !== undefined;
+}
+
+/** Extract `--mpreset <name>` (or `--mpreset=<name>`) from args, returning remaining positional args. */
+function extractModelPreset(args: string[]): { positional: string[]; modelPreset?: string } {
+	const positional: string[] = [];
+	let modelPreset: string | undefined;
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i]!;
+		if (arg === "--mpreset" && i + 1 < args.length) {
+			modelPreset = args[++i]!;
+		} else if (arg.startsWith("--mpreset=")) {
+			modelPreset = arg.slice("--mpreset=".length);
+		} else {
+			positional.push(arg);
+		}
+	}
+	return { positional, modelPreset };
 }
 
 /**
@@ -50,9 +94,14 @@ export function isLifecycleCommandText(text: string | undefined): boolean {
  * The caller MUST have already enforced paired-chat authorization; this function
  * performs grammar + target validation only.
  */
-export function parseLifecycleCommand(text: string | undefined): ParsedLifecycleCommand {
-	if (!isLifecycleCommandText(text)) return { kind: "none" };
+export function parseLifecycleCommand(
+	text: string | undefined,
+	ctx: { chatType?: string; botUsername?: string } = {},
+): ParsedLifecycleCommand {
 	const raw = (text ?? "").trim();
+	const [rawCommand, ...args] = raw.split(/\s+/);
+	const command = normalizeLifecycleCommandToken(rawCommand ?? "", ctx);
+	if (command === undefined) return { kind: "none" };
 
 	// MVP: reject any initial-prompt separator outright (no prompt handling yet).
 	if (/\s--(\s|$)/.test(raw)) {
@@ -63,8 +112,6 @@ export function parseLifecycleCommand(text: string | undefined): ParsedLifecycle
 		};
 	}
 
-	const [command, ...args] = raw.split(/\s+/);
-
 	if (command === "/session_recent") {
 		const which = args[0];
 		if (which === undefined || which === "create" || which === "resume") {
@@ -91,29 +138,33 @@ export function parseLifecycleCommand(text: string | undefined): ParsedLifecycle
 		return { kind: "resume", target: { sessionIdOrPrefix: idOrPrefix } };
 	}
 
-	// /session_create <kind> ...
-	const kind = args[0];
+	// /session_create <kind> ... [--mpreset <profile>]
+	const { positional, modelPreset } = extractModelPreset(args);
+	if (modelPreset !== undefined && !isSafeIdentifier(modelPreset)) {
+		return { kind: "reject", reason: "invalid_target", message: `Invalid model preset name.\n\n${USAGE}` };
+	}
+	const kind = positional[0];
 	if (kind === "path") {
-		if (args.length !== 2) return { kind: "usage", message: USAGE };
-		const p = normalizeLifecyclePath(args[1]!);
+		if (positional.length !== 2) return { kind: "usage", message: USAGE };
+		const p = normalizeLifecyclePath(positional[1]!);
 		if (!p) return { kind: "reject", reason: "invalid_target", message: `Invalid path.\n\n${USAGE}` };
-		return { kind: "create", target: { kind: "existing_path", path: p } };
+		return { kind: "create", target: { kind: "existing_path", path: p }, modelPreset };
 	}
 	if (kind === "dir") {
-		if (args.length !== 2) return { kind: "usage", message: USAGE };
-		const p = normalizeLifecyclePath(args[1]!);
+		if (positional.length !== 2) return { kind: "usage", message: USAGE };
+		const p = normalizeLifecyclePath(positional[1]!);
 		if (!p) return { kind: "reject", reason: "invalid_target", message: `Invalid dir.\n\n${USAGE}` };
-		return { kind: "create", target: { kind: "plain_dir", path: p } };
+		return { kind: "create", target: { kind: "plain_dir", path: p }, modelPreset };
 	}
 	if (kind === "worktree") {
-		if (args.length !== 3) return { kind: "usage", message: USAGE };
-		const repo = normalizeLifecyclePath(args[1]!);
-		const branch = args[2]!;
+		if (positional.length !== 3) return { kind: "usage", message: USAGE };
+		const repo = normalizeLifecyclePath(positional[1]!);
+		const branch = positional[2]!;
 		if (!repo) return { kind: "reject", reason: "invalid_target", message: `Invalid repo path.\n\n${USAGE}` };
 		if (!isSafeBranch(branch)) {
 			return { kind: "reject", reason: "invalid_target", message: `Invalid branch name.\n\n${USAGE}` };
 		}
-		return { kind: "create", target: { kind: "worktree", repo, branch } };
+		return { kind: "create", target: { kind: "worktree", repo, branch }, modelPreset };
 	}
 	return { kind: "usage", message: USAGE };
 }

package/src/notifications/lifecycle-control-runtime.ts

@@ -127,22 +127,27 @@ function tmuxSessionNameFor(sessionId: string): string {
  *  The launched session id is carried via `SKC_SESSION_ID` in the child env (see
  *  {@link daemonSpawnCreate}); the root `skc` launcher has no `--session-id`
  *  flag, so it must never appear in argv. Only flags the launch parser actually
- *  supports are emitted (`--worktree <branch>` for worktree targets). */
+ *  supports are emitted (`--worktree <branch>` for worktree targets,
+ *  `--mpreset <profile>` for model presets). */
 export function buildCreateArgv(
 	frame: SessionCreateFrame,
 	_ids: { intendedSessionId: string; startupPromptRef?: string },
 ): { cwd: string; args: string[] } {
+	const extraArgs: string[] = [];
+	if (frame.modelPreset) {
+		extraArgs.push("--mpreset", frame.modelPreset);
+	}
 	if (frame.target.kind === "worktree") {
 		const cwd = normalizeLifecyclePath(frame.target.repo);
 		if (!cwd) throw new Error("invalid_lifecycle_repo_path");
 		// Use the `--worktree=<branch>` form so the branch is a single argv token:
 		// a flag-shaped branch (e.g. `-x`) can never be mis-parsed as a separate
 		// launcher flag / detached-mode trigger.
-		return { cwd, args: [`--worktree=${frame.target.branch}`] };
+		return { cwd, args: [`--worktree=${frame.target.branch}`, ...extraArgs] };
 	}
 	const cwd = normalizeLifecyclePath(frame.target.path);
 	if (!cwd) throw new Error("invalid_lifecycle_path");
-	return { cwd, args: [] };
+	return { cwd, args: extraArgs };
 }
 
 /** Real daemon-safe tmux launcher: detached `tmux new-session -d` + SKC tags. */

package/src/notifications/lifecycle-orchestrator.ts

@@ -252,7 +252,17 @@ export async function handleLifecycleRequest(
 		return { status: "error", reason: "rate_limited", message: "create rate limit exceeded" };
 	}
 
-	// 4. Preallocate ids + write in_progress (fsynced) BEFORE any spawn.
+	// 4. Close is intentionally force-only until a graceful close contract exists.
+	if (frame.type === "session_close" && frame.force !== true) {
+		await deps.audit({ ...baseAudit, event: "rejected", reason: "invalid_target" });
+		return {
+			status: "error",
+			reason: "invalid_target",
+			message: "session_close requires force=true; graceful close is not supported",
+		};
+	}
+
+	// 5. Preallocate ids + write in_progress (fsynced) BEFORE any spawn.
 	const lifecycleRequestId = frame.type === "session_create" ? frame.lifecycleRequestId : deps.newLifecycleRequestId();
 	const intendedSessionId =
 		frame.type === "session_create" ? frame.intendedSessionId || deps.newSessionId() : deps.newSessionId();
@@ -344,15 +354,18 @@ export async function handleLifecycleRequest(
 		await deps.audit({ ...baseAudit, event: "success", sessionId: resumed.sessionId });
 		return { status: "ok", entry, mode: resumed.mode };
 	} catch (err) {
-		// A side effect may have occurred; do not auto-respawn. Mark terminal
-		// uncertain so a retry reconciles instead of duplicating.
+		// A side effect may have occurred; do not repeat it automatically. Mark
+		// terminal-uncertain so a retry reconciles instead of duplicating work.
+		let reason: LifecycleErrorReason = "terminal_uncertain";
+		if (frame.type === "session_create") reason = "spawn_failed";
+		if (frame.type === "session_close") reason = "close_refused";
 		Object.assign(entry, {
 			state: "terminal_uncertain",
 			updatedAt: deps.now(),
-			reason: "spawn_failed",
+			reason,
 		});
 		await deps.store.write(doc);
-		await deps.audit({ ...baseAudit, event: "terminal_uncertain", reason: "spawn_failed" });
-		return { status: "error", reason: "terminal_uncertain", message: `lifecycle effect failed: ${String(err)}` };
+		await deps.audit({ ...baseAudit, event: "terminal_uncertain", reason });
+		return { status: "error", reason: "terminal_uncertain", message: `${frame.type} effect failed: ${String(err)}` };
 	}
 }

package/src/notifications/reply-sent-store.ts

@@ -0,0 +1,134 @@
+/**
+ * Index of rich messages the daemon sent, mapping `${chat_id}:${message_id}` to
+ * the original markdown. Telegram does not echo a `sendRichMessage` message's
+ * text in a reply's `reply_to_message`, so a user replying to a rich final
+ * answer would otherwise strand the agent without the quoted context. The daemon
+ * records the markdown on every promoted send and looks it up on inbound replies
+ * to restore that context.
+ *
+ * Fail-closed and off-path-neutral: nothing is recorded unless a send was
+ * actually promoted to rich, `record` is a no-op on any error (the in-memory map
+ * is only mutated after the atomic persist succeeds), and `lookup` returns
+ * undefined on any miss or error, so a bad index write/read never kills the
+ * daemon.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { daemonPaths } from "./daemon-paths";
+
+/** Max distinct (chat, message) entries retained; oldest-by-timestamp evicted past this. */
+const MAX_ENTRIES = 1000;
+/** Max stored characters of the original markdown per entry. */
+const MAX_TEXT_LENGTH = 2000;
+/** Persisted index filename under the notifications directory. */
+const INDEX_FILENAME = "telegram-rich-sent-index.json";
+
+/**
+ * Minimal async filesystem surface the store needs. Structurally a subset of the
+ * daemon's `TelegramDaemonFs`, so the daemon can pass its own `fs` straight
+ * through and tests can inject a fake.
+ */
+export interface ReplySentStoreFs {
+	mkdir(path: string, opts?: fs.MakeDirectoryOptions): Promise<unknown>;
+	readFile(path: string, encoding: BufferEncoding): Promise<string>;
+	writeFile(path: string, data: string, opts?: fs.WriteFileOptions): Promise<void>;
+	rename(oldPath: string, newPath: string): Promise<void>;
+	chmod(path: string, mode: number): Promise<void>;
+}
+
+const nodeFs: ReplySentStoreFs = fs.promises as unknown as ReplySentStoreFs;
+
+interface StoredEntry {
+	text: string;
+	ts: number;
+}
+
+interface PersistShape {
+	version: 1;
+	entries: Record<string, StoredEntry>;
+}
+
+/** Compose the stable per-message key. */
+function keyFor(chatId: string | number, messageId: number): string {
+	return `${chatId}:${messageId}`;
+}
+
+/** Drop oldest-by-timestamp entries until at most {@link MAX_ENTRIES} remain. */
+function evictToCap(entries: Map<string, StoredEntry>): void {
+	if (entries.size <= MAX_ENTRIES) return;
+	// Stable sort keeps insertion order among equal timestamps, so the oldest
+	// inserted entry is evicted first when timestamps tie.
+	const oldestFirst = [...entries.entries()].sort((a, b) => a[1].ts - b[1].ts);
+	const overflow = entries.size - MAX_ENTRIES;
+	for (let i = 0; i < overflow; i++) entries.delete(oldestFirst[i]![0]);
+}
+
+export class ReplySentStore {
+	readonly #dir: string;
+	readonly #file: string;
+	readonly #fsImpl: ReplySentStoreFs;
+	readonly #now: () => number;
+	#entries = new Map<string, StoredEntry>();
+
+	constructor(input: { agentDir: string; fs?: ReplySentStoreFs; now?: () => number }) {
+		this.#dir = daemonPaths(input.agentDir).dir;
+		this.#file = path.join(this.#dir, INDEX_FILENAME);
+		this.#fsImpl = input.fs ?? nodeFs;
+		this.#now = input.now ?? Date.now;
+	}
+
+	/** Restore the persisted index into memory. No-op on a missing or corrupt file. */
+	async load(): Promise<void> {
+		try {
+			const parsed = JSON.parse(await this.#fsImpl.readFile(this.#file, "utf8")) as Partial<PersistShape>;
+			const restored = new Map<string, StoredEntry>();
+			for (const [key, value] of Object.entries(parsed?.entries ?? {})) {
+				if (value && typeof value.text === "string" && typeof value.ts === "number") {
+					restored.set(key, { text: value.text, ts: value.ts });
+				}
+			}
+			evictToCap(restored);
+			this.#entries = restored;
+		} catch {
+			// Missing/corrupt index: keep the current in-memory map (empty on first load).
+		}
+	}
+
+	/**
+	 * Record the original markdown of a rich message the daemon just sent. The
+	 * text is capped at {@link MAX_TEXT_LENGTH}; the index is capped at
+	 * {@link MAX_ENTRIES} (oldest-by-timestamp evicted). No-op on any failure: the
+	 * in-memory map is only replaced after the atomic persist succeeds.
+	 */
+	async record(input: { chatId: string | number; messageId: number; text: string }): Promise<void> {
+		try {
+			const text = input.text.length > MAX_TEXT_LENGTH ? input.text.slice(0, MAX_TEXT_LENGTH) : input.text;
+			const next = new Map(this.#entries);
+			next.set(keyFor(input.chatId, input.messageId), { text, ts: this.#now() });
+			evictToCap(next);
+			await this.#persist(next);
+			this.#entries = next;
+		} catch {
+			// Best-effort: never let an index write kill the daemon.
+		}
+	}
+
+	/** Look up the original markdown for a message the daemon sent. undefined on miss or failure. */
+	lookup(input: { chatId: string | number; messageId: number }): string | undefined {
+		try {
+			return this.#entries.get(keyFor(input.chatId, input.messageId))?.text;
+		} catch {
+			return undefined;
+		}
+	}
+
+	async #persist(entries: Map<string, StoredEntry>): Promise<void> {
+		await this.#fsImpl.mkdir(this.#dir, { recursive: true, mode: 0o700 });
+		const payload: PersistShape = { version: 1, entries: Object.fromEntries(entries) };
+		const tmp = `${this.#file}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`;
+		await this.#fsImpl.writeFile(tmp, `${JSON.stringify(payload, null, 2)}\n`, { mode: 0o600 });
+		await this.#fsImpl.chmod(tmp, 0o600).catch(() => undefined);
+		await this.#fsImpl.rename(tmp, this.#file);
+	}
+}

package/src/notifications/rich-draft.ts

@@ -0,0 +1,107 @@
+/**
+ * Opt-in rich-draft streaming for a turn's in-progress preview.
+ *
+ * When the operator opts in (`richDraft.enabled`) the daemon streams LIVE turn
+ * markdown to the Bot API `sendRichMessageDraft` method as a debounced preview.
+ * Every failure is a harmless no-op (warn once, keep the daemon alive), and when
+ * off no draft call is ever made — so the off-state request bodies stay
+ * byte-identical.
+ */
+
+import type { BotApi } from "./telegram-daemon";
+import type { ThreadedSend } from "./threaded-render";
+
+/** Minimum gap between two draft sends for one session (debounce floor). */
+export const DRAFT_DEBOUNCE_MS = 1_500;
+
+/**
+ * Wrap raw markdown + a monotonic draft id in the `sendRichMessageDraft` request
+ * payload shape: mirrors `buildRichMessage`'s proven `rich_message.markdown`
+ * content wrapper, with a top-level `draft_id` selecting the draft revision to
+ * update (a routing param, like `message_thread_id`).
+ */
+export function buildRichDraft(draftId: number, raw: string): { draft_id: number; rich_message: { markdown: string } } {
+	return { draft_id: draftId, rich_message: { markdown: raw } };
+}
+
+/**
+ * Whether a granted send should stream a rich draft. Fail-closed: every clause
+ * must hold, otherwise no draft is sent. Mirrors `shouldPromoteRich` but targets
+ * the LIVE lane and the live-only `richDraftMarkdown` marker (set by
+ * `renderThreadedFrame` for non-finalized turn frames).
+ */
+export function shouldStreamDraft(input: { enabled?: boolean; send: ThreadedSend }): boolean {
+	const { enabled, send } = input;
+	return (
+		enabled === true &&
+		send.method === "sendMessage" &&
+		send.lane === "live" &&
+		typeof send.richDraftMarkdown === "string" &&
+		send.richDraftMarkdown.trim().length > 0
+	);
+}
+
+/**
+ * Per-session debounce + monotonic draft-id state for draft streaming. Skips a
+ * draft when less than `debounceMs` has elapsed since the session's last SENT
+ * draft (the rate-limit pool already coalesces live frames to the latest, so a
+ * skipped frame is naturally superseded by the next one). `reset` clears a
+ * session's window when its turn finalizes so the next turn starts fresh.
+ */
+export class DraftStreamState {
+	readonly #debounceMs: number;
+	readonly #lastSentAt = new Map<string, number>();
+	/** Daemon-global monotonic draft id: unique across sessions so two sessions
+	 * sharing one flat chat (no per-topic thread key) never collide on draft id. */
+	#nextDraftId = 0;
+
+	constructor(debounceMs: number = DRAFT_DEBOUNCE_MS) {
+		this.#debounceMs = debounceMs;
+	}
+
+	/**
+	 * If enough time has elapsed since the session's last draft, record `now` as
+	 * the new last-sent time and return the next monotonic draft id; otherwise
+	 * return `undefined` (debounced — the caller skips this frame).
+	 */
+	tryClaim(sessionId: string, now: number): number | undefined {
+		const last = this.#lastSentAt.get(sessionId);
+		if (last !== undefined && now - last < this.#debounceMs) return undefined;
+		this.#lastSentAt.set(sessionId, now);
+		const id = ++this.#nextDraftId;
+		return id;
+	}
+
+	/** Clear a session's debounce window (called when its turn finalizes). The
+	 * global draft id keeps incrementing so ids are never reused across turns. */
+	reset(sessionId: string): void {
+		this.#lastSentAt.delete(sessionId);
+	}
+}
+
+/**
+ * Best-effort delivery of a rich draft. Never throws and has no HTML fallback: a
+ * draft is a purely additive preview, so on any failure (a thrown transport
+ * error or an `{ ok: false }` JSON response — the transport returns `res.json()`
+ * for JSON methods, so `ok:false` does not throw) it warns exactly once and
+ * returns; the unchanged live HTML send still carries the content.
+ */
+export async function deliverDraft(
+	botApi: BotApi,
+	base: { chat_id: string | number; message_thread_id?: number },
+	draftId: number,
+	raw: string,
+	log?: { warn(msg: string): void },
+): Promise<void> {
+	let failure: string | undefined;
+	try {
+		const res = await botApi.call("sendRichMessageDraft", { ...base, ...buildRichDraft(draftId, raw) });
+		if (res !== null && typeof res === "object" && (res as { ok?: unknown }).ok === false) {
+			const description = (res as { description?: unknown }).description;
+			failure = typeof description === "string" && description.length > 0 ? description : "ok:false";
+		}
+	} catch (err) {
+		failure = err instanceof Error ? err.message : String(err);
+	}
+	if (failure !== undefined) log?.warn(`notifications: sendRichMessageDraft failed (${failure}); draft skipped`);
+}

package/src/notifications/rich-render.ts

@@ -0,0 +1,142 @@
+/**
+ * Rich-message promotion for stable non-editable Telegram text sends.
+ *
+ * When enabled, the daemon promotes eligible finalized `sendMessage` payloads
+ * carrying raw markdown to the Bot API `sendRichMessage` method. On any miss or
+ * failure the daemon keeps the unchanged HTML `sendMessage` path, so the
+ * off-state request bodies are byte-identical.
+ */
+
+import type { BotApi } from "./telegram-daemon";
+import type { ThreadedSend } from "./threaded-render";
+
+/**
+ * Telegram's hard per-message character ceiling (4096). Surfaced here purely as
+ * documentation and a marker for a future native rich-message splitter — it is
+ * intentionally NON-BEHAVIORAL and MUST stay that way: nothing in the rich path
+ * branches on this value.
+ *
+ * Overflow is already safe without it. The production final-answer text is capped
+ * at 3500 chars upstream (`summaryFromMessage(..., 3500)`), so a promoted
+ * `sendRichMessage` never approaches this ceiling; and if the Bot API ever rejects
+ * an oversized rich payload it returns `{ ok: false }`, which
+ * `deliverRichWithFallback` (below) turns into the chunked HTML `splitTelegramHtml`
+ * fallback (each chunk ≤ TELEGRAM_MESSAGE_LIMIT). This constant only marks where a
+ * future rich splitter would read its ceiling; wiring it into a branch would change
+ * byte-for-byte behavior and is out of scope.
+ */
+export const RICH_MESSAGE_LIMIT = 4096;
+
+/** Wrap raw markdown in the `sendRichMessage` request payload shape. */
+export function buildRichMessage(
+	raw: string,
+	extras: { reply_markup?: unknown } = {},
+): { rich_message: { markdown: string }; reply_markup?: unknown } {
+	return { rich_message: { markdown: raw }, ...extras };
+}
+
+/**
+ * Whether a granted send should be promoted to `sendRichMessage`. Fail-closed
+ * and class-aware: every clause must hold, otherwise the daemon keeps the HTML path.
+ */
+export function shouldPromoteRich(input: { enabled?: boolean; send: ThreadedSend }): boolean {
+	const { enabled, send } = input;
+	return (
+		enabled === true &&
+		send.method === "sendMessage" &&
+		send.lane === "finalized" &&
+		send.richClass === "final" &&
+		send.editable !== true &&
+		typeof send.richMarkdown === "string" &&
+		send.richMarkdown.trim().length > 0 &&
+		typeof send.text === "string" &&
+		send.text.length > 0
+	);
+}
+
+/**
+ * Deliver the promoted rich message, falling back to `fallbackDeliver` (the
+ * unchanged HTML `sendMessage` loop) on any failure. A failure is either a
+ * thrown transport error or a `{ ok: false }` JSON response (the transport
+ * returns `res.json()` for JSON methods, so `ok:false` does not throw). On
+ * failure exactly one diagnostic is logged before the fallback runs; on success
+ * the fallback never runs.
+ *
+ * Returns the sent message's `message_id` on success (when the response carries
+ * one), otherwise `undefined` — including every failure/fallback path and a
+ * success whose response omits `result.message_id`. Callers that ignore the
+ * return value are unaffected.
+ */
+export async function deliverRichWithFallback(
+	botApi: BotApi,
+	base: { chat_id: string | number; message_thread_id?: number },
+	send: ThreadedSend,
+	fallbackDeliver: () => Promise<void>,
+	log?: { warn(msg: string): void },
+): Promise<number | undefined> {
+	let failure: string | undefined;
+	let messageId: number | undefined;
+	try {
+		const res = await botApi.call("sendRichMessage", { ...base, ...buildRichMessage(send.richMarkdown!) });
+		if (res !== null && typeof res === "object" && (res as { ok?: unknown }).ok === false) {
+			const description = (res as { description?: unknown }).description;
+			failure = typeof description === "string" && description.length > 0 ? description : "ok:false";
+		} else {
+			const candidate = (res as { result?: { message_id?: unknown } } | null)?.result?.message_id;
+			if (typeof candidate === "number") messageId = candidate;
+		}
+	} catch (err) {
+		failure = err instanceof Error ? err.message : String(err);
+	}
+	if (failure === undefined) return messageId;
+	log?.warn(`notifications: sendRichMessage failed (${failure}); falling back to HTML`);
+	await fallbackDeliver();
+	return undefined;
+}
+
+/**
+ * Deliver an action-needed (ask/idle) message via `sendRichMessage`, falling
+ * back to the unchanged HTML chunk loop on any failure. Mirrors
+ * {@link deliverRichWithFallback} but takes an explicit markdown body plus an
+ * optional top-level `reply_markup` (probe-confirmed: `sendRichMessage` accepts
+ * `reply_markup` alongside `rich_message`), and surfaces a structured outcome so
+ * the daemon can route inbound replies to the resulting message id.
+ *
+ * On rich success: returns `{ messageId, usedRich: true, usedFallback: false }`
+ * where `messageId` is `res.result.message_id` when present. On a `{ ok:false }`
+ * response or a thrown transport error: warns exactly once, runs `htmlFallback`,
+ * and returns `{ messageId, usedRich: false, usedFallback: true }` where
+ * `messageId` is the fallback's return value (the last HTML chunk's id).
+ */
+export async function deliverRichActionWithFallback(
+	botApi: BotApi,
+	base: { chat_id: string | number; message_thread_id?: number },
+	opts: { markdown: string; replyMarkup?: unknown; requireMessageId?: boolean },
+	htmlFallback: () => Promise<number | undefined>,
+	log?: { warn(msg: string): void },
+): Promise<{ messageId?: number; usedRich: boolean; usedFallback: boolean }> {
+	let failure: string | undefined;
+	let messageId: number | undefined;
+	try {
+		const res = await botApi.call("sendRichMessage", {
+			...base,
+			...buildRichMessage(opts.markdown, opts.replyMarkup === undefined ? {} : { reply_markup: opts.replyMarkup }),
+		});
+		if (res !== null && typeof res === "object" && (res as { ok?: unknown }).ok === false) {
+			const description = (res as { description?: unknown }).description;
+			failure = typeof description === "string" && description.length > 0 ? description : "ok:false";
+		} else {
+			const candidate = (res as { result?: { message_id?: unknown } } | null)?.result?.message_id;
+			if (typeof candidate === "number") messageId = candidate;
+			// Ask messages MUST be reply-routable: if a rich success carries no numeric
+			// message_id, fall back to HTML so a routable id is guaranteed.
+			else if (opts.requireMessageId) failure = "rich response missing message_id";
+		}
+	} catch (err) {
+		failure = err instanceof Error ? err.message : String(err);
+	}
+	if (failure === undefined) return { messageId, usedRich: true, usedFallback: false };
+	log?.warn(`notifications: sendRichMessage(action) failed (${failure}); falling back to HTML`);
+	const fallbackId = await htmlFallback();
+	return { messageId: fallbackId, usedRich: false, usedFallback: true };
+}

package/src/notifications/telegram-daemon-control.ts

@@ -20,7 +20,7 @@ import type {
 	DaemonStatus,
 } from "../daemon/control-types";
 import { resolveSkcRuntimeSpawnInfo } from "../daemon/runtime";
-import { getNotificationConfig, isGloballyConfigured, tokenFingerprint } from "./config";
+import { getNotificationConfig, isTelegramConfigured, tokenFingerprint } from "./config";
 import {
 	daemonPaths,
 	isFreshLiveOwner,
@@ -159,7 +159,7 @@ export class TelegramDaemonController implements BuiltInDaemonController {
 	async status(): Promise<DaemonStatus> {
 		const runtime = this.runtimeInfo();
 		const cfg = getNotificationConfig(this.settings);
-		const configured = isGloballyConfigured(cfg) && Boolean(cfg.botToken) && Boolean(cfg.chatId);
+		const configured = isTelegramConfigured(cfg);
 		if (!configured) {
 			return { kind: this.kind, configured: false, health: "not_configured", runtime };
 		}
@@ -269,6 +269,7 @@ export class TelegramDaemonController implements BuiltInDaemonController {
 				{ settings: this.settings, roots, tokenFingerprint: fp, chatId },
 				this.spawnDeps(),
 			);
+			warnings.push(...spawned.warnings);
 			const after = await this.status();
 			return this.result(
 				action,
@@ -351,6 +352,7 @@ export class TelegramDaemonController implements BuiltInDaemonController {
 			{ settings: this.settings, roots, tokenFingerprint: fp, chatId },
 			this.spawnDeps(),
 		);
+		warnings.push(...spawned.warnings);
 		const after = await this.status();
 		if (spawned.result === "attached") {
 			// A live owner already exists; attaching to it is a valid running end-state.
@@ -360,7 +362,7 @@ export class TelegramDaemonController implements BuiltInDaemonController {
 		}
 		return this.result(
 			action,
-			spawned.result !== "disabled",
+			spawned.result !== "disabled" && spawned.result !== "blocked",
 			`reloaded telegram daemon (${spawned.result})`,
 			before,
 			after,