@sayknow-cli/coding-agent 0.3.6 → 0.3.8

package/src/notifications/index.ts

@@ -26,15 +26,15 @@ import * as path from "node:path";
 import { promisify } from "node:util";
 import type { ImageContent, TextContent } from "@sayknow-cli/ai";
 import { NotificationServer } from "@sayknow-cli/natives";
-import { logger } from "@sayknow-cli/utils";
+import { logger, postmortem } from "@sayknow-cli/utils";
 import { Settings } from "../config/settings";
-import type { ExtensionCommandContext, ExtensionContext, ExtensionFactory } from "../extensibility/extensions";
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "../extensibility/extensions";
 import { registerAskAnswerSource } from "../tools/ask-answer-registry";
 import { registerTelegramFileSink } from "./attachment-registry";
 import {
 	getNotificationConfig,
-	isGloballyConfigured,
 	isSessionNotificationsEnabled,
+	isTelegramConfigured,
 	type NotificationConfig,
 	sessionTag,
 } from "./config";
@@ -100,7 +100,7 @@ export interface SessionCloseFrame {
 	chatId: string;
 	token: string;
 	target: SessionCloseTarget;
-	/** Hard-kill even if a live pane is attached (SKC-managed only). */
+	/** Required force-only close flag; false/omitted is rejected by daemon policy. */
 	force?: boolean;
 }
 
@@ -297,6 +297,15 @@ function buildIdentity(
 	return { repo, branch, machine: os.hostname(), title: sessionName };
 }
 
+/** Compact cwd label for remote session identity; never emits the full host path by default. */
+function compactCwd(cwd: string): string | undefined {
+	const home = os.homedir();
+	const resolved = path.resolve(cwd);
+	if (resolved === home) return "~";
+	const base = path.basename(resolved);
+	return base || path.parse(resolved).root || undefined;
+}
+
 const execFileAsync = promisify(execFile);
 
 /** Best-effort working-tree diff stat for the context update (no throw). */
@@ -327,6 +336,8 @@ interface SessionRuntime {
 	disposeAnswerSource: () => void;
 	/** Deregisters this session's Telegram file sink. */
 	disposeFileSink: () => void;
+	/** Deregisters this session's unattended workflow-gate listener. */
+	disposeGateListener: () => void;
 	redact: boolean;
 	verbosity: "lean" | "verbose";
 	sessionTag: string;
@@ -339,6 +350,14 @@ interface SessionRuntime {
 	/** Assistant text already flushed before an ask this turn (turn-scoped dedupe
 	 * so turn_end does not re-emit the pre-ask lead-in). Reset each turn. */
 	preAskFlushedText?: string;
+	/** Live streaming: opt-in flag, monotonic per-turn ref, and emit throttle state. */
+	stream: boolean;
+	turnSeq?: number;
+	liveRef?: string;
+	lastLiveAt?: number;
+	lastLiveText?: string;
+	/** Cancels the postmortem cleanup that emits `session_closed` on process teardown. */
+	cancelPostmortemCleanup: () => void;
 }
 
 interface ResolvedSettings {
@@ -347,6 +366,8 @@ interface ResolvedSettings {
 	settingsAvailable: boolean;
 }
 
+const TELEGRAM_FILE_REDACTION_ERROR = "Telegram file attachments are disabled while notifications redaction is on.";
+
 const defaultConfig: NotificationConfig = {
 	enabled: false,
 	botToken: undefined,
@@ -368,7 +389,36 @@ export function notificationsEnabled(): boolean {
 	return process.env.SKC_NOTIFICATIONS === "1" || Boolean(process.env.SKC_NOTIFICATIONS_TOKEN);
 }
 
-function resolveSettings(): ResolvedSettings {
+// Live streaming (opt-in): emit throttled non-finalized `turn_stream` frames as
+// the assistant message streams so remote clients can edit ONE message live. The
+// finalized frame (turn_end) carries the same messageRef and stays authoritative,
+// so a dropped live frame self-heals. Off unless SKC_NOTIFICATIONS_STREAM=1.
+function streamingEnabled(): boolean {
+	return process.env.SKC_NOTIFICATIONS_STREAM === "1";
+}
+function streamIntervalMs(): number {
+	return Math.max(200, Number(process.env.SKC_NOTIFICATIONS_STREAM_INTERVAL_MS) || 500);
+}
+// Max chars of a turn's assistant text carried by the FINALIZED turn_stream (and
+// the pre-ask capture). Default 3500 keeps the mirror a glanceable per-turn
+// summary; a client that splits long messages (the Telegram daemon does so via
+// splitTelegramHtml, scheduling each chunk through the shared rate-limit pool so
+// the fan-out never bypasses the per-chat limit) can raise it with
+// SKC_NOTIFICATIONS_TURN_MAX to deliver full turns. The value is clamped to a
+// finite [280, TURN_TEXT_MAX_CEILING] range: a non-finite or non-positive env
+// (unset, NaN, Infinity, <= 0) falls back to the default, so the cap can never
+// be unbounded. Live frames are intentionally NOT raised — they stay one
+// editable preview message rather than fanning a long in-progress turn across
+// sends.
+const TURN_TEXT_MAX_CEILING = 40_000;
+function turnTextMax(): number {
+	const raw = Number(process.env.SKC_NOTIFICATIONS_TURN_MAX);
+	if (!Number.isFinite(raw) || raw <= 0) return 3500;
+	return Math.min(TURN_TEXT_MAX_CEILING, Math.max(280, raw));
+}
+function resolveSettings(settingsOverride?: Settings): ResolvedSettings {
+	if (settingsOverride)
+		return { settings: settingsOverride, cfg: getNotificationConfig(settingsOverride), settingsAvailable: true };
 	try {
 		const settings = Settings.instance;
 		return { settings, cfg: getNotificationConfig(settings), settingsAvailable: true };
@@ -480,7 +530,7 @@ function sessionIdFromFile(file: string | undefined): string | undefined {
 	return underscore >= 0 ? base.slice(underscore + 1) : undefined;
 }
 
-export const createNotificationsExtension: ExtensionFactory = api => {
+export function createNotificationsExtension(api: ExtensionAPI, options: { settings?: Settings } = {}): void {
 	const runtimes = new Map<string, SessionRuntime>();
 	const disabledSessions = new Set<string>();
 	const sessionId = (ctx: ExtensionContext): string => ctx.sessionManager.getSessionId();
@@ -490,10 +540,18 @@ export const createNotificationsExtension: ExtensionFactory = api => {
 		const rt = runtimes.get(id);
 		if (!rt) return false;
 		runtimes.delete(id);
+		try {
+			rt.cancelPostmortemCleanup();
+		} catch {}
 		try {
 			rt.disposeAnswerSource();
+		} catch {}
+		try {
 			rt.disposeFileSink();
 		} catch {}
+		try {
+			rt.disposeGateListener();
+		} catch {}
 		// Resolve any still-pending interactive asks so the ask tool is not left hanging.
 		for (const pending of rt.pendingInteractive.values()) pending.resolve(undefined);
 		rt.pendingInteractive.clear();
@@ -517,10 +575,14 @@ export const createNotificationsExtension: ExtensionFactory = api => {
 		return isSessionNotificationsEnabled({ cfg, env: process.env, sessionDisabled: disabledSessions.has(id) });
 	}
 
+	function isNotificationEligibleContext(ctx: ExtensionContext): boolean {
+		return ctx.sessionMetadata?.kind !== "sub";
+	}
+
 	async function startSession(ctx: ExtensionContext): Promise<"started" | "already" | "disabled" | "failed"> {
 		const id = sessionId(ctx);
-		const { settings, cfg, settingsAvailable } = resolveSettings();
-		if (!isEnabledForSession(id, cfg)) return "disabled";
+		const { settings, cfg, settingsAvailable } = resolveSettings(options.settings);
+		if (!isNotificationEligibleContext(ctx) || !isEnabledForSession(id, cfg)) return "disabled";
 		if (runtimes.has(id)) return "already";
 
 		const stateRoot = path.join(ctx.cwd, ".skc", "state");
@@ -648,6 +710,10 @@ export const createNotificationsExtension: ExtensionFactory = api => {
 				tag,
 			);
 			const disposeFileSink = registerTelegramFileSink(id, async file => {
+				if (runtime?.redact ?? redact) {
+					return { ok: false, error: TELEGRAM_FILE_REDACTION_ERROR };
+				}
+
 				try {
 					const data = await fs.promises.readFile(file.path);
 					server.pushFrame(
@@ -671,16 +737,28 @@ export const createNotificationsExtension: ExtensionFactory = api => {
 				pendingInteractive,
 				disposeAnswerSource,
 				disposeFileSink,
+				disposeGateListener: () => {},
+				cancelPostmortemCleanup: () => {},
 				redact,
 				verbosity,
+				stream: streamingEnabled(),
 				sessionTag: tag,
 				busy: false,
 				pendingInbound: new Set<number>(),
 			};
 			runtimes.set(id, runtime);
+			// A native terminal close (SIGHUP), SIGTERM, Ctrl+C exit, or fatal error
+			// skips AgentSession.dispose(), so the `session_shutdown` extension event
+			// never fires and the daemon-side topic would be orphaned. postmortem
+			// awaits registered cleanups on those paths, so send the graceful
+			// `session_closed` frame from there too. stopSession() cancels this
+			// registration on every other teardown path, so it never double-fires.
+			runtime.cancelPostmortemCleanup = postmortem.register(`notifications-session-closed:${id}`, async () => {
+				await stopSession(id);
+			});
 			logger.info(`notifications: serving session ${id} at ${endpoint.url} (unattended=${unattended})`);
 
-			if (settingsAvailable && settings && isGloballyConfigured(cfg)) {
+			if (settingsAvailable && settings && isTelegramConfigured(cfg)) {
 				try {
 					await ensureTelegramDaemonRunning({ settings, cwd: ctx.cwd, sessionId: id });
 				} catch (e) {
@@ -704,7 +782,7 @@ export const createNotificationsExtension: ExtensionFactory = api => {
 
 			// Unattended: a real ask emits a workflow gate; register it repliable by gate_id.
 			if (unattended && gate?.onGateEmitted) {
-				gate.onGateEmitted(g => {
+				runtime.disposeGateListener = gate.onGateEmitted(g => {
 					const options = (g.options ?? []).map(o => String((o as { label?: unknown }).label ?? ""));
 					gateOptions.set(g.gate_id, options);
 					const promptCtx = g.context as { prompt?: unknown; title?: unknown } | undefined;
@@ -739,7 +817,7 @@ export const createNotificationsExtension: ExtensionFactory = api => {
 		async handler(args: string, ctx: ExtensionCommandContext): Promise<void> {
 			const id = sessionId(ctx);
 			const command = args.trim().split(/\s+/, 1)[0]?.toLowerCase() || "status";
-			const resolved = resolveSettings();
+			const resolved = resolveSettings(options.settings);
 			const enabledWithoutLocalOff = isSessionNotificationsEnabled({
 				cfg: resolved.cfg,
 				env: process.env,
@@ -759,6 +837,10 @@ export const createNotificationsExtension: ExtensionFactory = api => {
 			}
 
 			if (command === "on") {
+				if (!isNotificationEligibleContext(ctx)) {
+					ctx.ui.notify("Notifications are disabled for subagent sessions.", "warning");
+					return;
+				}
 				if (process.env.SKC_NOTIFICATIONS === "0") {
 					ctx.ui.notify(
 						"Notifications remain disabled: SKC_NOTIFICATIONS=0 is an authoritative opt-out.",
@@ -839,9 +921,15 @@ export const createNotificationsExtension: ExtensionFactory = api => {
 		// Re-bind the interactive ask answer source: the ask tool resolves the
 		// source by the current session id, which just changed.
 		try {
+			rt.cancelPostmortemCleanup();
 			rt.disposeAnswerSource();
 			rt.disposeFileSink();
 		} catch {}
+		// Follow the id change so a later process teardown closes the re-keyed
+		// session (the old closure captured the retired id).
+		rt.cancelPostmortemCleanup = postmortem.register(`notifications-session-closed:${newId}`, async () => {
+			await stopSession(newId);
+		});
 		rt.disposeAnswerSource = registerInteractiveAnswerSource(
 			newId,
 			rt.server,
@@ -850,6 +938,10 @@ export const createNotificationsExtension: ExtensionFactory = api => {
 			rt.sessionTag,
 		);
 		rt.disposeFileSink = registerTelegramFileSink(newId, async file => {
+			if (rt.redact) {
+				return { ok: false, error: TELEGRAM_FILE_REDACTION_ERROR };
+			}
+
 			try {
 				const data = await fs.promises.readFile(file.path);
 				rt.server.pushFrame(
@@ -973,7 +1065,8 @@ export const createNotificationsExtension: ExtensionFactory = api => {
 			const tokenUsage = usage && usage.tokens != null ? `${usage.tokens}/${usage.contextWindow}` : undefined;
 			const modelId = model?.id;
 			void readGitDiffStat(ctx.cwd).then(diff => {
-				if (!diff && !tokenUsage && !modelId) return;
+				const cwd = compactCwd(ctx.cwd);
+				if (!diff && !tokenUsage && !modelId && !cwd) return;
 				try {
 					rt.server.pushFrame(
 						JSON.stringify({
@@ -982,6 +1075,7 @@ export const createNotificationsExtension: ExtensionFactory = api => {
 							tokenUsage,
 							model: modelId,
 							diff,
+							cwd,
 						}),
 					);
 				} catch (e) {
@@ -1003,7 +1097,15 @@ export const createNotificationsExtension: ExtensionFactory = api => {
 		if (!text || text === rt.preAskFlushedText) return;
 		rt.preAskFlushedText = text;
 		try {
-			rt.server.pushFrame(JSON.stringify({ type: "turn_stream", sessionId: id, phase: "finalized", text }));
+			rt.server.pushFrame(
+				JSON.stringify({
+					type: "turn_stream",
+					sessionId: id,
+					phase: "finalized",
+					text,
+					...(rt.liveRef ? { messageRef: rt.liveRef } : {}),
+				}),
+			);
 		} catch (e) {
 			logger.warn(`notifications: pushFrame (turn) failed: ${String(e)}`);
 		}
@@ -1027,12 +1129,43 @@ export const createNotificationsExtension: ExtensionFactory = api => {
 		const id = sessionId(ctx);
 		const rt = runtimes.get(id);
 		if (!rt) return;
-		const text = rt.redact ? undefined : summaryFromMessage(event.message, 3500);
+		const text = rt.redact ? undefined : summaryFromMessage(event.message, turnTextMax());
 		if (text) flushTurnText(rt, id, text);
 		// Reset per-turn streaming state so the next turn starts fresh and a later
 		// turn with identical text is not falsely deduped.
 		rt.currentTurnText = undefined;
 		rt.preAskFlushedText = undefined;
+		rt.liveRef = undefined;
+		rt.lastLiveAt = undefined;
+		rt.lastLiveText = undefined;
+	});
+
+	// Live streaming (opt-in): push throttled in-progress assistant text as
+	// non-finalized turn_stream frames so remote clients edit one message as the
+	// turn streams. The finalized frame (turn_end) carries the same messageRef and
+	// lands the authoritative text. Suppressed under redaction.
+	api.on("message_update", (event, ctx) => {
+		const id = sessionId(ctx);
+		const rt = runtimes.get(id);
+		if (!rt?.stream || rt.redact) return;
+		if ((event.message as { role?: unknown }).role !== "assistant") return;
+		if (rt.liveRef === undefined) {
+			rt.turnSeq = (rt.turnSeq ?? 0) + 1;
+			rt.liveRef = String(rt.turnSeq);
+		}
+		const now = Date.now();
+		if (now - (rt.lastLiveAt ?? 0) < streamIntervalMs()) return;
+		const text = summaryFromMessage(event.message, 3500);
+		if (!text || text === rt.lastLiveText) return;
+		rt.lastLiveAt = now;
+		rt.lastLiveText = text;
+		try {
+			rt.server.pushFrame(
+				JSON.stringify({ type: "turn_stream", sessionId: id, phase: "live", text, messageRef: rt.liveRef }),
+			);
+		} catch (e) {
+			logger.warn(`notifications: pushFrame (live) failed: ${String(e)}`);
+		}
 	});
 
 	// Stream agent-produced images (computer/browser/tool screenshots) as
@@ -1046,7 +1179,7 @@ export const createNotificationsExtension: ExtensionFactory = api => {
 		// flush can emit it before the ask prompt. Role-scoped: message_end also
 		// fires for the user prompt, which must never be mirrored back as turn output.
 		if ((event.message as { role?: unknown }).role === "assistant") {
-			const turnText = summaryFromMessage(event.message, 3500);
+			const turnText = summaryFromMessage(event.message, turnTextMax());
 			if (turnText) rt.currentTurnText = turnText;
 		}
 		for (const img of imageAttachmentsFromMessage(event.message)) {
@@ -1069,4 +1202,4 @@ export const createNotificationsExtension: ExtensionFactory = api => {
 	api.on("session_shutdown", async (_event, ctx) => {
 		await stopSession(sessionId(ctx));
 	});
-};
+}

package/src/notifications/lifecycle-commands.ts

@@ -15,6 +15,19 @@ 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 =
@@ -36,10 +49,24 @@ const USAGE = [
 	"/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;
 }
 
 /**
@@ -50,9 +77,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 +95,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") {

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

@@ -238,6 +238,7 @@ export function daemonResumeSession(env: NodeJS.ProcessEnv = process.env, opts:
 		// restart, so an unknown or ambiguous prefix fails closed instead of
 		// blindly spawning `skc --resume <prefix>` against a non-authoritative id.
 		let resumeId = target.sessionIdOrPrefix;
+		let resumeCwd = target.path;
 		if (opts.sessionsRoot) {
 			const saved = listRecentSessions({ sessionsRoot: opts.sessionsRoot, limit: 1000 });
 			const prefixed = saved.filter(
@@ -249,11 +250,19 @@ export function daemonResumeSession(env: NodeJS.ProcessEnv = process.env, opts:
 			if (resolved.length > 1) {
 				return { ambiguous: resolved.map(s => ({ sessionId: s.sessionId, path: s.path })) };
 			}
-			resumeId = resolved[0]!.sessionId;
+			const selected = resolved[0]!;
+			resumeId = selected.sessionId;
+			resumeCwd = selected.path;
+		}
+		const resolvedResumeCwd = resumeCwd ? path.resolve(resumeCwd) : undefined;
+		const resumeCwdStat = resolvedResumeCwd ? fs.statSync(resolvedResumeCwd, { throwIfNoEntry: false }) : undefined;
+		if (!resumeCwdStat?.isDirectory()) {
+			throw new Error(`skc_lifecycle_resume_cwd_unavailable: ${resolvedResumeCwd ?? "(missing)"}`);
 		}
 		const tmux = resolveSkcTmuxCommand(env);
 		const name = tmuxSessionNameFor(resumeId);
-		const command = `exec env SKC_TMUX_LAUNCHED=1 SKC_NOTIFICATIONS=1 skc --resume ${shellQuote(resumeId)}`;
+		const cwdPrefix = resolvedResumeCwd ? `cd ${shellQuote(resolvedResumeCwd)} && ` : "";
+		const command = `${cwdPrefix}exec env SKC_TMUX_LAUNCHED=1 SKC_NOTIFICATIONS=1 skc --resume ${shellQuote(resumeId)}`;
 		const r = Bun.spawnSync([tmux, "new-session", "-d", "-s", name, "sh", "-c", command], {
 			stdout: "pipe",
 			stderr: "pipe",
@@ -261,7 +270,7 @@ export function daemonResumeSession(env: NodeJS.ProcessEnv = process.env, opts:
 		});
 		if (r.exitCode !== 0) throw new Error(r.stderr.toString().trim() || "skc_lifecycle_resume_failed");
 		const tgt = buildSkcTmuxExactOptionTarget(name);
-		for (const cmd of buildSkcTmuxProfileCommands(tgt, env, { sessionId: resumeId })) {
+		for (const cmd of buildSkcTmuxProfileCommands(tgt, env, { sessionId: resumeId, project: resolvedResumeCwd })) {
 			Bun.spawnSync([tmux, ...cmd.args], { stdout: "pipe", stderr: "pipe", env });
 		}
 		return {

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/recent-activity.ts

@@ -25,6 +25,8 @@ export interface RecentSessionEntry {
 	mtimeMs: number;
 	/** True when a terminal breadcrumb points at this session file. */
 	currentTerminal?: boolean;
+	/** True when this history is an internal helper/sub-agent session. */
+	internal?: boolean;
 }
 
 export interface RecentActivityDeps {
@@ -34,17 +36,18 @@ export interface RecentActivityDeps {
 	breadcrumbPaths?: string[];
 	/** Max entries to return (default 20). */
 	limit?: number;
+	/** Include internal helper/sub-agent sessions (default true). */
+	includeInternal?: boolean;
 	/** Injection seam for tests. */
-	readFirstLine?: (file: string) => string | undefined;
+	readInitialLines?: (file: string, maxLines: number) => string[];
 }
 
-function defaultReadFirstLine(file: string): string | undefined {
+function defaultReadInitialLines(file: string, maxLines: number): string[] {
 	try {
-		const buf = fs.readFileSync(file, "utf8");
-		const nl = buf.indexOf("\n");
-		return nl === -1 ? buf : buf.slice(0, nl);
+		const lines = fs.readFileSync(file, "utf8").split("\n");
+		return lines.slice(0, maxLines);
 	} catch {
-		return undefined;
+		return [];
 	}
 }
 
@@ -65,6 +68,22 @@ function headerMeta(line: string | undefined): { id?: string; path?: string; bra
 	}
 }
 
+/** Detect task-tool helper sessions from the durable early session_init metadata entry. */
+function isInternalSession(lines: readonly string[]): boolean {
+	for (const line of lines.slice(1)) {
+		if (!line.trim()) continue;
+		try {
+			const obj = JSON.parse(line) as unknown;
+			if (typeof obj === "object" && obj !== null && (obj as { type?: unknown }).type === "session_init") {
+				return true;
+			}
+		} catch {
+			// Ignore malformed JSONL entries; classification is best-effort.
+		}
+	}
+	return false;
+}
+
 /**
  * The authoritative session id for a history file: the header `id` when present,
  * else the filename stem with a leading `<timestamp>_` prefix stripped (matching
@@ -85,7 +104,8 @@ function sessionIdForFile(stem: string, headerId: string | undefined): string {
  */
 export function listRecentSessions(deps: RecentActivityDeps): RecentSessionEntry[] {
 	const limit = deps.limit ?? 20;
-	const readFirstLine = deps.readFirstLine ?? defaultReadFirstLine;
+	const includeInternal = deps.includeInternal ?? true;
+	const readInitialLines = deps.readInitialLines ?? defaultReadInitialLines;
 	const breadcrumbs = new Set((deps.breadcrumbPaths ?? []).map(p => path.resolve(p)));
 
 	let projectDirs: string[];
@@ -114,7 +134,10 @@ export function listRecentSessions(deps: RecentActivityDeps): RecentSessionEntry
 			} catch {
 				continue;
 			}
-			const meta = headerMeta(readFirstLine(file));
+			const initialLines = readInitialLines(file, 8);
+			const meta = headerMeta(initialLines[0]);
+			const internal = isInternalSession(initialLines);
+			if (internal && !includeInternal) continue;
 			entries.push({
 				sessionId: sessionIdForFile(name.slice(0, -".jsonl".length), meta.id),
 				path: meta.path,
@@ -123,6 +146,7 @@ export function listRecentSessions(deps: RecentActivityDeps): RecentSessionEntry
 				sessionStateFile: file,
 				mtimeMs,
 				currentTerminal: breadcrumbs.has(path.resolve(file)) || undefined,
+				internal: internal || undefined,
 			});
 		}
 	}

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

@@ -3,12 +3,19 @@ import * as path from "node:path";
 import { YAML } from "bun";
 import type { Settings } from "../config/settings";
 import { getNotificationConfig, isGloballyConfigured } from "./config";
-import { daemonPaths, TelegramNotificationDaemon } from "./telegram-daemon";
-import { clearTelegramControlRequest, readTelegramControlRequest } from "./telegram-daemon-control";
+import { daemonPaths } from "./daemon-paths";
+import type { TelegramDaemonOptions } from "./telegram-daemon";
+
+type TelegramDaemonRunner = {
+	run(): Promise<void>;
+	requestStop(reason?: "reload" | "signal" | "stop"): void;
+};
+
+type TelegramDaemonConstructor = new (opts: TelegramDaemonOptions) => TelegramDaemonRunner;
 
 export interface RunDaemonInternalDeps {
 	SettingsImpl?: { init: (options?: { agentDir?: string }) => Promise<Pick<Settings, "get" | "getAgentDir">> };
-	DaemonImpl?: typeof TelegramNotificationDaemon;
+	DaemonImpl?: TelegramDaemonConstructor;
 	processPid?: number;
 	pidAlive?: (pid: number) => boolean;
 }
@@ -140,7 +147,9 @@ export async function runDaemonInternal(argv: string[], deps: RunDaemonInternalD
 	const settings = await resolveDaemonSettings(resolvedAgentDir, deps);
 	const cfg = getNotificationConfig(settings as Settings);
 	if (!isGloballyConfigured(cfg) || !cfg.botToken || !cfg.chatId) return;
-	const Daemon = deps.DaemonImpl ?? TelegramNotificationDaemon;
+	const { clearTelegramControlRequest, readTelegramControlRequest } = await import("./telegram-daemon-control");
+	const Daemon: TelegramDaemonConstructor =
+		deps.DaemonImpl ?? (await import("./telegram-daemon")).TelegramNotificationDaemon;
 	const daemon = new Daemon({
 		settings: settings as Settings,
 		ownerId,