@gajae-code/coding-agent 0.7.2 → 0.7.4

package/src/notifications/lifecycle-commands.ts

@@ -0,0 +1,228 @@
+/**
+ * Paired-chat /session_* command grammar (G009).
+ *
+ * Pure parser + shared target validator for the Telegram session-lifecycle
+ * commands. The daemon parses an inbound paired-chat message here, then attaches
+ * transport identity (chatId/updateId/token/requestId) and routes the resulting
+ * frame to the orchestrator. Keeping this pure makes the grammar, the MVP
+ * prompt-rejection, and target validation unit-testable without the daemon.
+ *
+ * MVP scope: an initial prompt (`-- <prompt>`) is REJECTED with usage text — no
+ * prompt text ever enters a frame, audit, log, or response until daemon-owned
+ * 0600 prompt refs are designed.
+ */
+import type { SessionCloseTarget, SessionCreateTarget, SessionLifecycleResponse, SessionResumeTarget } from "./index";
+
+export type LifecycleCommandVerb = "session_create" | "session_close" | "session_resume";
+
+/** A parsed, validated lifecycle command (transport identity added by caller). */
+export type ParsedLifecycleCommand =
+	| { kind: "create"; target: SessionCreateTarget }
+	| { kind: "close"; target: SessionCloseTarget }
+	| { kind: "resume"; target: SessionResumeTarget }
+	| { kind: "recent"; which: "create" | "resume" | "all" }
+	| { kind: "usage"; message: string }
+	| { kind: "reject"; reason: "invalid_target" | "prompt_unsupported"; message: string }
+	| { kind: "none" };
+
+const USAGE = [
+	"Session commands:",
+	"/session_create path <dir>",
+	"/session_create worktree <repo> <branch>",
+	"/session_create dir <newdir>",
+	"/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 {
+	if (!text) return false;
+	return /^\/session_(create|close|resume|recent)\b/.test(text.trim());
+}
+
+/**
+ * Parse a paired-chat message into a lifecycle command. Returns `none` for
+ * non-lifecycle text, `usage`/`reject` for malformed input (no side effect), or
+ * a validated `create`/`close`/`resume`/`recent` intent.
+ *
+ * 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" };
+	const raw = (text ?? "").trim();
+
+	// MVP: reject any initial-prompt separator outright (no prompt handling yet).
+	if (/\s--(\s|$)/.test(raw)) {
+		return {
+			kind: "reject",
+			reason: "prompt_unsupported",
+			message: `Initial prompts (\`-- <prompt>\`) are not supported yet. Create the session, then send a normal message in its thread.\n\n${USAGE}`,
+		};
+	}
+
+	const [command, ...args] = raw.split(/\s+/);
+
+	if (command === "/session_recent") {
+		const which = args[0];
+		if (which === undefined || which === "create" || which === "resume") {
+			return { kind: "recent", which: which ?? "all" };
+		}
+		return { kind: "usage", message: USAGE };
+	}
+
+	if (command === "/session_close") {
+		if (args.length !== 1) return { kind: "usage", message: USAGE };
+		const sessionId = args[0]!;
+		if (!isSafeIdentifier(sessionId)) {
+			return { kind: "reject", reason: "invalid_target", message: `Invalid session id.\n\n${USAGE}` };
+		}
+		return { kind: "close", target: { sessionId } };
+	}
+
+	if (command === "/session_resume") {
+		if (args.length !== 1) return { kind: "usage", message: USAGE };
+		const idOrPrefix = args[0]!;
+		if (!isSafeIdentifier(idOrPrefix)) {
+			return { kind: "reject", reason: "invalid_target", message: `Invalid session id/prefix.\n\n${USAGE}` };
+		}
+		return { kind: "resume", target: { sessionIdOrPrefix: idOrPrefix } };
+	}
+
+	// /session_create <kind> ...
+	const kind = args[0];
+	if (kind === "path") {
+		if (args.length !== 2) return { kind: "usage", message: USAGE };
+		const p = args[1]!;
+		if (!isSafePath(p)) return { kind: "reject", reason: "invalid_target", message: `Invalid path.\n\n${USAGE}` };
+		return { kind: "create", target: { kind: "existing_path", path: p } };
+	}
+	if (kind === "dir") {
+		if (args.length !== 2) return { kind: "usage", message: USAGE };
+		const p = args[1]!;
+		if (!isSafePath(p)) return { kind: "reject", reason: "invalid_target", message: `Invalid dir.\n\n${USAGE}` };
+		return { kind: "create", target: { kind: "plain_dir", path: p } };
+	}
+	if (kind === "worktree") {
+		if (args.length !== 3) return { kind: "usage", message: USAGE };
+		const repo = args[1]!;
+		const branch = args[2]!;
+		if (!isSafePath(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: "usage", message: USAGE };
+}
+
+/** The canonical usage text (exported for the daemon's help replies). */
+export function lifecycleUsage(): string {
+	return USAGE;
+}
+
+/**
+ * Shared target validator reused at the policy/effect boundary (after paired-chat
+ * auth, before any side effect). Returns null when valid, or an `invalid_target`
+ * reason. The orchestrator remains authoritative; this is a defensive pre-check
+ * the parser and any other entry point share.
+ */
+export function validateLifecycleTarget(
+	verb: LifecycleCommandVerb,
+	target: SessionCreateTarget | SessionCloseTarget | SessionResumeTarget,
+): { ok: true } | { ok: false; reason: "invalid_target"; message: string } {
+	const bad = (message: string) => ({ ok: false as const, reason: "invalid_target" as const, message });
+	if (verb === "session_create") {
+		const t = target as SessionCreateTarget;
+		if (t.kind === "existing_path" || t.kind === "plain_dir") {
+			return isSafePath(t.path) ? { ok: true } : bad("invalid path");
+		}
+		if (t.kind === "worktree") {
+			if (!isSafePath(t.repo)) return bad("invalid repo path");
+			return isSafeBranch(t.branch) ? { ok: true } : bad("invalid branch");
+		}
+		return bad("unknown create target");
+	}
+	if (verb === "session_close") {
+		const t = target as SessionCloseTarget;
+		return isSafeIdentifier(t.sessionId) ? { ok: true } : bad("invalid session id");
+	}
+	const t = target as SessionResumeTarget;
+	return isSafeIdentifier(t.sessionIdOrPrefix) ? { ok: true } : bad("invalid session id/prefix");
+}
+
+// --- Safety primitives (defensive; the full-trust paired chat is accepted, but
+// we still reject obviously malformed/injection-shaped inputs early). ---
+
+function isSafeIdentifier(value: string): boolean {
+	return /^[A-Za-z0-9._-]{1,128}$/.test(value);
+}
+
+function isSafePath(value: string): boolean {
+	// Reject empty, shell-metacharacter, or newline-bearing paths. Absolute or
+	// relative are both allowed (full-trust chat), but not injection shapes.
+	if (value.length === 0 || value.length > 4096) return false;
+	if (/[\n\r\0]/.test(value)) return false;
+	return !/[;&|`$(){}<>*?!\\"']/.test(value);
+}
+
+function isSafeBranch(value: string): boolean {
+	// Defense-in-depth: also reject leading-hyphen names so a branch can never be
+	// mistaken for a CLI flag downstream.
+	return /^[A-Za-z0-9._/-]{1,255}$/.test(value) && !value.includes("..") && !value.startsWith("-");
+}
+
+/**
+ * Map a lifecycle response/error to a user-facing Telegram message (G010).
+ *
+ * Only derives text from sessionId, mode, reason, a safe message, and candidate
+ * {sessionId,path} — never a token or prompt. Each error reason gets tailored,
+ * actionable copy; an "in progress" pending response is surfaced distinctly.
+ */
+export function formatLifecycleOutcome(r: SessionLifecycleResponse): string {
+	switch (r.type) {
+		case "session_create_response":
+			return `\u{1f680} Launching session ${r.sessionId} in tmux. It will appear once ready \u2014 check /session_recent.`;
+		case "session_close_response":
+			return `\u2705 Closed session ${r.sessionId} (history preserved \u2014 you can resume it later).`;
+		case "session_resume_response":
+			return r.mode === "reattached"
+				? `\u2705 Reattached to live session ${r.sessionId}.`
+				: `\u{1f680} Cold-restarting session ${r.sessionId} from saved history in tmux \u2014 check /session_recent.`;
+		case "session_lifecycle_error":
+			break;
+		default:
+			return "Unknown lifecycle response.";
+	}
+	if (r.reason === "ambiguous_target" && r.candidates?.length) {
+		const list = r.candidates.map(c => `\u2022 ${c.sessionId}${c.path ? ` (${c.path})` : ""}`).join("\n");
+		return `\u2753 Multiple sessions match \u2014 reply with the exact id:\n${list}`;
+	}
+	switch (r.reason) {
+		case "unauthorized":
+			return "\u26d4 Not authorized for session lifecycle commands.";
+		case "rate_limited":
+			return "\u23f3 Too many create requests \u2014 please wait a bit and try again.";
+		case "duplicate_conflict":
+			return "\u26a0\ufe0f That command id was already used for a different request; send a fresh command.";
+		case "invalid_target":
+			return `\u26a0\ufe0f Invalid target. ${r.message}`;
+		case "spawn_failed":
+			return "\u26a0\ufe0f The session failed to start. Nothing was left running.";
+		case "discovery_timeout":
+		case "readiness_timeout":
+			return "\u23f3 The session did not become ready in time. It may still be starting \u2014 check /session_recent.";
+		case "close_refused":
+			return "\u26a0\ufe0f Close refused: that session is not GJC-managed or did not match.";
+		case "not_found":
+			return "\u2753 No matching session was found.";
+		case "terminal_uncertain":
+			return /in progress/i.test(r.message)
+				? "\u23f3 That request is already in progress \u2014 hold on."
+				: "\u26a0\ufe0f Outcome uncertain. Check /session_recent before retrying so you don't double-spawn.";
+		default:
+			return `\u26a0\ufe0f ${r.reason}: ${r.message}`;
+	}
+}

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

@@ -0,0 +1,400 @@
+/**
+ * Wires the authenticated Rust control endpoint (NotificationControlServer) to
+ * the lifecycle orchestrator with REAL daemon-side effects: a daemon-safe tmux
+ * launcher (create / cold-restart), force-close, and reattach-or-cold-restart
+ * resume. Kept separate from telegram-daemon.ts so the effects + wiring are
+ * unit-testable; the daemon calls {@link attachLifecycleControl} once it owns
+ * the control server.
+ */
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import {
+	buildGjcTmuxExactOptionTarget,
+	buildGjcTmuxProfileCommands,
+	resolveGjcTmuxCommand,
+} from "../gjc-runtime/tmux-common";
+import {
+	findGjcTmuxSessionByName,
+	forceCloseGjcTmuxSession,
+	listGjcTmuxSessions,
+	statusGjcTmuxSession,
+} from "../gjc-runtime/tmux-sessions";
+import type { ResumeCandidate, SessionCreateFrame, SessionLifecycleRequest, SessionLifecycleResponse } from "./index";
+import {
+	type AuditEvent,
+	type CreateEffectResult,
+	handleLifecycleRequest,
+	type LedgerDoc,
+	type LedgerStore,
+	type LifecycleOutcome,
+	type OrchestratorDeps,
+	type ResumeEffectResult,
+} from "./lifecycle-orchestrator";
+import { listRecentSessions } from "./recent-activity";
+
+/** Minimal view of the native control server this runtime depends on. */
+export interface ControlServerLike {
+	onLifecycleRequest(
+		cb: (err: Error | null, req: { kind: string; requestId: string; payloadJson: string }) => void,
+	): void;
+	respond(responseJson: string): void;
+}
+
+/**
+ * A startable control server (the native NotificationControlServer, or a fake in
+ * tests). Extends {@link ControlServerLike} with the start/stop lifecycle the
+ * daemon owns.
+ */
+export interface LifecycleControlServer extends ControlServerLike {
+	start(): Promise<unknown>;
+	stop(): void;
+}
+
+/** Factory the daemon uses to construct a control server bound to its ownership. */
+export type LifecycleControlServerFactory = (input: {
+	token: string;
+	ownerId: string;
+	agentDir: string;
+}) => LifecycleControlServer;
+
+/** Atomic + fsynced file-backed idempotency ledger store. */
+export function fileLedgerStore(idempotencyFile: string): LedgerStore {
+	return {
+		async read(): Promise<LedgerDoc> {
+			try {
+				return JSON.parse(fs.readFileSync(idempotencyFile, "utf8")) as LedgerDoc;
+			} catch {
+				return { version: 1, entries: {} };
+			}
+		},
+		async write(doc: LedgerDoc): Promise<void> {
+			fs.mkdirSync(path.dirname(idempotencyFile), { recursive: true });
+			const tmp = `${idempotencyFile}.${process.pid}.${Date.now()}.tmp`;
+			const fd = fs.openSync(tmp, "w", 0o600);
+			fs.writeSync(fd, JSON.stringify(doc));
+			fs.fsyncSync(fd);
+			fs.closeSync(fd);
+			fs.renameSync(tmp, idempotencyFile);
+			// fsync the parent directory so the rename itself is durable across a
+			// crash / power loss (the temp-file fsync alone does not persist the
+			// directory entry).
+			try {
+				const dirFd = fs.openSync(path.dirname(idempotencyFile), "r");
+				try {
+					fs.fsyncSync(dirFd);
+				} finally {
+					fs.closeSync(dirFd);
+				}
+			} catch {
+				// Some platforms reject directory fsync; the rename is still atomic.
+			}
+		},
+	};
+}
+
+/** Append-only JSONL audit sink (0600). Never receives tokens or raw prompts. */
+export function fileAudit(auditPath: string): (e: AuditEvent) => void {
+	return (e: AuditEvent) => {
+		fs.mkdirSync(path.dirname(auditPath), { recursive: true });
+		fs.appendFileSync(auditPath, `${JSON.stringify(e)}\n`, { mode: 0o600 });
+	};
+}
+
+/** Simple per-chat sliding-window create rate limiter. */
+export function createRateLimiter(maxPerWindow: number, windowMs: number): (chatId: string, nowMs: number) => boolean {
+	const hits = new Map<string, number[]>();
+	return (chatId: string, nowMs: number) => {
+		const arr = (hits.get(chatId) ?? []).filter(t => nowMs - t < windowMs);
+		if (arr.length >= maxPerWindow) {
+			hits.set(chatId, arr);
+			return false;
+		}
+		arr.push(nowMs);
+		hits.set(chatId, arr);
+		return true;
+	};
+}
+
+function tmuxSessionNameFor(sessionId: string): string {
+	return `gjc_lc_${sessionId}`;
+}
+
+/** Build the `gjc` argv for a create target (existing path / worktree / dir).
+ *
+ *  The launched session id is carried via `GJC_SESSION_ID` in the child env (see
+ *  {@link daemonSpawnCreate}); the root `gjc` 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). */
+export function buildCreateArgv(
+	frame: SessionCreateFrame,
+	_ids: { intendedSessionId: string; startupPromptRef?: string },
+): { cwd: string; args: string[] } {
+	if (frame.target.kind === "worktree") {
+		// 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: frame.target.repo, args: [`--worktree=${frame.target.branch}`] };
+	}
+	return { cwd: frame.target.path, args: [] };
+}
+
+/** Real daemon-safe tmux launcher: detached `tmux new-session -d` + GJC tags. */
+export function daemonSpawnCreate(env: NodeJS.ProcessEnv = process.env) {
+	return async (
+		frame: SessionCreateFrame,
+		ids: { lifecycleRequestId: string; intendedSessionId: string; startupPromptRef?: string },
+	): Promise<CreateEffectResult> => {
+		const tmux = resolveGjcTmuxCommand(env);
+		const name = tmuxSessionNameFor(ids.intendedSessionId);
+		const { cwd, args } = buildCreateArgv(frame, ids);
+		// A `plain_dir` target is a NEW working directory: create it before spawn
+		// so `/session_create dir <newdir>` works as documented.
+		if (frame.target.kind === "plain_dir") {
+			fs.mkdirSync(cwd, { recursive: true });
+		}
+		// Detached: no interactive TTY needed (daemon-safe).
+		const childEnv: Record<string, string> = {
+			GJC_TMUX_LAUNCHED: "1",
+			GJC_NOTIFICATIONS: "1",
+			GJC_SESSION_ID: ids.intendedSessionId,
+			GJC_LIFECYCLE_REQUEST_ID: ids.lifecycleRequestId,
+		};
+		if (ids.startupPromptRef) childEnv.GJC_STARTUP_PROMPT_REF = ids.startupPromptRef;
+		const envPairs = Object.entries(childEnv)
+			.map(([k, v]) => `${k}=${shellQuote(v)}`)
+			.join(" ");
+		const command = `cd ${shellQuote(cwd)} && exec env ${envPairs} gjc ${args.map(shellQuote).join(" ")}`;
+		const created = Bun.spawnSync([tmux, "new-session", "-d", "-s", name, "sh", "-c", command], {
+			stdout: "pipe",
+			stderr: "pipe",
+			env,
+		});
+		if (created.exitCode !== 0) {
+			throw new Error(created.stderr.toString().trim() || "gjc_lifecycle_spawn_failed");
+		}
+		const target = buildGjcTmuxExactOptionTarget(name);
+		const metaCommands = buildGjcTmuxProfileCommands(target, env, {
+			sessionId: ids.intendedSessionId,
+			project: cwd,
+		});
+		for (const cmd of metaCommands) {
+			Bun.spawnSync([tmux, ...cmd.args], { stdout: "pipe", stderr: "pipe", env });
+		}
+		const status = statusGjcTmuxSession(name, env);
+		return {
+			sessionId: ids.intendedSessionId,
+			tmuxSession: name,
+			sessionStateFile: status.sessionStateFile,
+			endpointUrl: "",
+			topicThreadId: "",
+		};
+	};
+}
+
+/** Real force-close effect (GJC-managed only, id-matched). */
+export function daemonCloseSession(env: NodeJS.ProcessEnv = process.env) {
+	return async (target: { sessionId: string; tmuxSession?: string; sessionStateFile?: string }) => {
+		const name = target.tmuxSession ?? tmuxSessionNameFor(target.sessionId);
+		forceCloseGjcTmuxSession(name, env, target.sessionId, target.sessionStateFile);
+		return { processGone: findGjcTmuxSessionByName(name, env) === undefined };
+	};
+}
+
+/** Real resume effect: reattach if a live GJC session matches; else resolve the
+ *  prefix against saved history and fail closed (`ambiguous`/`notFound`) before
+ *  cold-restarting exactly one resolved session via the daemon-safe launcher. */
+export function daemonResumeSession(env: NodeJS.ProcessEnv = process.env, opts: { sessionsRoot?: string } = {}) {
+	return async (target: {
+		sessionIdOrPrefix: string;
+		path?: string;
+	}): Promise<ResumeEffectResult | { ambiguous: ResumeCandidate[] } | { notFound: true }> => {
+		const live = listGjcTmuxSessions(env).filter(
+			s => s.sessionId === target.sessionIdOrPrefix || s.sessionId?.startsWith(target.sessionIdOrPrefix),
+		);
+		if (live.length > 1) {
+			return {
+				ambiguous: live.map(s => ({ sessionId: s.sessionId ?? s.name, path: s.project })),
+			};
+		}
+		if (live.length === 1) {
+			const s = live[0]!;
+			return {
+				sessionId: s.sessionId ?? s.name,
+				tmuxSession: s.name,
+				sessionStateFile: s.sessionStateFile,
+				endpointUrl: "",
+				topicThreadId: "",
+				mode: "reattached",
+			};
+		}
+		// Dead: resolve the id/prefix against saved session history BEFORE cold
+		// restart, so an unknown or ambiguous prefix fails closed instead of
+		// blindly spawning `gjc --resume <prefix>` against a non-authoritative id.
+		let resumeId = target.sessionIdOrPrefix;
+		if (opts.sessionsRoot) {
+			const saved = listRecentSessions({ sessionsRoot: opts.sessionsRoot, limit: 1000 });
+			const prefixed = saved.filter(
+				s => s.sessionId === target.sessionIdOrPrefix || s.sessionId.startsWith(target.sessionIdOrPrefix),
+			);
+			const exact = prefixed.filter(s => s.sessionId === target.sessionIdOrPrefix);
+			const resolved = exact.length > 0 ? exact : prefixed;
+			if (resolved.length === 0) return { notFound: true };
+			if (resolved.length > 1) {
+				return { ambiguous: resolved.map(s => ({ sessionId: s.sessionId, path: s.path })) };
+			}
+			resumeId = resolved[0]!.sessionId;
+		}
+		const tmux = resolveGjcTmuxCommand(env);
+		const name = tmuxSessionNameFor(resumeId);
+		const command = `exec env GJC_TMUX_LAUNCHED=1 GJC_NOTIFICATIONS=1 gjc --resume ${shellQuote(resumeId)}`;
+		const r = Bun.spawnSync([tmux, "new-session", "-d", "-s", name, "sh", "-c", command], {
+			stdout: "pipe",
+			stderr: "pipe",
+			env,
+		});
+		if (r.exitCode !== 0) throw new Error(r.stderr.toString().trim() || "gjc_lifecycle_resume_failed");
+		const tgt = buildGjcTmuxExactOptionTarget(name);
+		for (const cmd of buildGjcTmuxProfileCommands(tgt, env, { sessionId: resumeId })) {
+			Bun.spawnSync([tmux, ...cmd.args], { stdout: "pipe", stderr: "pipe", env });
+		}
+		return {
+			sessionId: resumeId,
+			tmuxSession: name,
+			endpointUrl: "",
+			topicThreadId: "",
+			mode: "cold_restarted",
+		};
+	};
+}
+
+function shellQuote(value: string): string {
+	return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+/** Translate an orchestrator outcome into a wire response frame. */
+export function outcomeToResponse(frame: SessionLifecycleRequest, outcome: LifecycleOutcome): SessionLifecycleResponse {
+	if (outcome.status === "error" || outcome.status === "pending") {
+		const reason = outcome.status === "pending" ? "terminal_uncertain" : outcome.reason;
+		return {
+			type: "session_lifecycle_error",
+			requestId: frame.requestId,
+			status: "error",
+			reason,
+			message: outcome.status === "pending" ? "request already in progress" : outcome.message,
+			...(outcome.status === "error" && outcome.candidates ? { candidates: outcome.candidates } : {}),
+		};
+	}
+	const e = outcome.entry;
+	if (frame.type === "session_create") {
+		return {
+			type: "session_create_response",
+			requestId: frame.requestId,
+			status: "ok",
+			lifecycleRequestId: frame.lifecycleRequestId,
+			sessionId: e.sessionId ?? e.intendedSessionId ?? "",
+			matchedBy: "spawn_marker",
+			endpoint: { url: e.endpointUrl ?? "", token: "" },
+			topic: { chatId: frame.chatId, threadId: "" },
+			target: frame.target,
+		};
+	}
+	if (frame.type === "session_close") {
+		return {
+			type: "session_close_response",
+			requestId: frame.requestId,
+			status: "ok",
+			sessionId: e.sessionId ?? "",
+			processGone: e.processGone ?? false,
+			historyPreserved: true,
+			// The killed session's per-session endpoint record is reaped by the
+			// daemon's dead-PID scan (scanRoots), so it is effectively stale.
+			endpointStale: e.processGone ?? false,
+		};
+	}
+	return {
+		type: "session_resume_response",
+		requestId: frame.requestId,
+		status: "ok",
+		sessionId: e.sessionId ?? "",
+		mode: outcome.mode ?? "reattached",
+		endpoint: { url: e.endpointUrl ?? "", token: "" },
+		topic: { chatId: frame.chatId, threadId: "" },
+	};
+}
+
+/**
+ * Wire a control server's lifecycle requests through the orchestrator.
+ *
+ * Handlers run on a single serial queue (a promise chain): the daemon owns the
+ * one control endpoint, so serializing here makes each request's ledger
+ * read -> classify -> write atomic with respect to every other request. Two
+ * identical updates that arrive nearly simultaneously can no longer both
+ * classify as `new` and both spawn — the second sees the first's persisted
+ * `in_progress`/`success` entry and re-acks instead.
+ */
+export function attachLifecycleControl(server: ControlServerLike, deps: OrchestratorDeps): void {
+	let queue: Promise<void> = Promise.resolve();
+	server.onLifecycleRequest((err, req) => {
+		if (err) return;
+		let frame: SessionLifecycleRequest;
+		try {
+			frame = JSON.parse(req.payloadJson) as SessionLifecycleRequest;
+		} catch {
+			return;
+		}
+		queue = queue
+			.then(async () => {
+				const outcome = await handleLifecycleRequest(frame, deps);
+				server.respond(JSON.stringify(outcomeToResponse(frame, outcome)));
+			})
+			.catch(() => {
+				// A handler failure must not break the queue for later requests.
+			});
+	});
+}
+
+/** Assemble real orchestrator deps for the daemon (ledger/audit under agentDir). */
+export function buildOrchestratorDeps(input: {
+	pairedChatId: string;
+	agentNotificationsDir: string;
+	/** Root of saved session histories (`<agentDir>/sessions`), for resume resolution. */
+	sessionsRoot?: string;
+	env?: NodeJS.ProcessEnv;
+}): OrchestratorDeps {
+	const env = input.env ?? process.env;
+	return {
+		pairedChatId: input.pairedChatId,
+		now: () => Date.now(),
+		store: fileLedgerStore(path.join(input.agentNotificationsDir, "telegram-lifecycle-idempotency.json")),
+		audit: fileAudit(path.join(input.agentNotificationsDir, "telegram-lifecycle-audit.jsonl")),
+		allowCreate: createRateLimiter(3, 10 * 60 * 1000),
+		writeStartupPrompt: async (requestId, prompt) => {
+			if (prompt === undefined) return undefined;
+			const ref = path.join(input.agentNotificationsDir, `startup-prompt-${requestId}`);
+			fs.mkdirSync(path.dirname(ref), { recursive: true });
+			const fd = fs.openSync(ref, "w", 0o600);
+			fs.writeSync(fd, prompt);
+			fs.fsyncSync(fd);
+			fs.closeSync(fd);
+			return ref;
+		},
+		spawnCreate: daemonSpawnCreate(env),
+		closeSession: daemonCloseSession(env),
+		resumeSession: daemonResumeSession(env, { sessionsRoot: input.sessionsRoot }),
+		newLifecycleRequestId: () => `lc-${crypto.randomUUID()}`,
+		newSessionId: () => `s${crypto.randomUUID().slice(0, 8)}`,
+	};
+}
+
+/**
+ * Default production factory: a real native NotificationControlServer bound to
+ * the daemon's control token, owner id, and agent dir.
+ */
+export const createNativeControlServer: LifecycleControlServerFactory = ({ token, ownerId, agentDir }) => {
+	// Lazy require so loading this module (for the orchestrator / wiring / tests)
+	// never eagerly resolves the native addon — only a real production start does.
+	const { NotificationControlServer } = require("@gajae-code/natives") as typeof import("@gajae-code/natives");
+	return new NotificationControlServer(token, ownerId, agentDir) as unknown as LifecycleControlServer;
+};