@sayknow-cli/coding-agent 0.4.7 → 0.5.0

package/src/sdk/bus/reconciliation-store.ts

@@ -0,0 +1,224 @@
+/**
+ * Session-scoped durable store for kind-aware invocation reconciliation (#3032/#3035).
+ *
+ * Path is always a private sibling of the transcript, never under artifactsDir:
+ *   <dirname(sessionFile)>/.sdk-reconciliation/<safeSessionId>.json
+ *
+ * Safe session ids only: /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/
+ * Atomic write: temp + fsync + rename + 0600. Corrupt → quarantine + empty.
+ * Non-terminal records settle to failed/process_restart on bootstrap (recon incomplete).
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type { PromptCorrelation, PromptReconciliationStatus } from "./prompt-reconciliation";
+
+export const RECONCILIATION_STORE_VERSION = 1;
+export const RECONCILIATION_SESSION_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+export const RECONCILIATION_DIR_NAME = ".sdk-reconciliation";
+
+export type ReconciliationKind = "prompt" | "skill";
+
+export interface DurableReconciliationRecord extends PromptCorrelation {
+	kind: ReconciliationKind;
+	clientRef?: string;
+	status: PromptReconciliationStatus;
+	error?: { code: string; message: string };
+	acceptedAt: number;
+	startedAt?: number;
+	terminalAt?: number;
+	/** Skill-only safe token; never skill args bodies. */
+	skillName?: string;
+}
+
+export interface ReconciliationStoreDocument {
+	version: typeof RECONCILIATION_STORE_VERSION;
+	sessionId: string;
+	records: DurableReconciliationRecord[];
+}
+
+export interface ReconciliationStoreFs {
+	mkdir(directory: string, options: { recursive: true; mode: number }): Promise<unknown>;
+	readFile(file: string, encoding: "utf8"): Promise<string>;
+	writeFile(file: string, data: string, options: { mode: number }): Promise<void>;
+	rename(from: string, to: string): Promise<void>;
+	unlink(file: string): Promise<void>;
+	open(
+		file: string,
+		flags: string,
+	): Promise<{
+		sync(): Promise<void>;
+		close(): Promise<void>;
+		writeFile(data: string, encoding: "utf8"): Promise<void>;
+	}>;
+}
+
+const nodeFs: ReconciliationStoreFs = {
+	mkdir: fs.mkdir,
+	readFile: fs.readFile,
+	writeFile: fs.writeFile,
+	rename: fs.rename,
+	unlink: fs.unlink,
+	open: fs.open as ReconciliationStoreFs["open"],
+};
+
+export function isSafeReconciliationSessionId(sessionId: string): boolean {
+	return RECONCILIATION_SESSION_ID_PATTERN.test(sessionId);
+}
+
+/** Derive private store path; throws if sessionId is unsafe (path escape). */
+export function reconciliationStorePath(sessionFile: string, sessionId: string): string {
+	if (!isSafeReconciliationSessionId(sessionId))
+		throw Object.assign(new Error("Unsafe session id for reconciliation store path."), {
+			code: "invalid_input",
+		});
+	return path.join(path.dirname(sessionFile), RECONCILIATION_DIR_NAME, `${sessionId}.json`);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function parseDocument(raw: string, expectedSessionId: string): ReconciliationStoreDocument {
+	const value = JSON.parse(raw) as unknown;
+	if (!isRecord(value) || value.version !== RECONCILIATION_STORE_VERSION)
+		throw new Error("invalid reconciliation store version");
+	if (value.sessionId !== expectedSessionId) throw new Error("session id mismatch");
+	if (!Array.isArray(value.records)) throw new Error("invalid records");
+	return value as unknown as ReconciliationStoreDocument;
+}
+
+/**
+ * Settle non-terminal durable records after process death: failed/process_restart.
+ * Meaning: reconciliation incomplete — not proof of agent failure.
+ */
+export function settleProcessRestart(
+	records: DurableReconciliationRecord[],
+	now: number,
+): DurableReconciliationRecord[] {
+	return records.map(record => {
+		if (record.terminalAt !== undefined) return record;
+		return {
+			...record,
+			status: "failed",
+			terminalAt: now,
+			error: { code: "process_restart", message: "Reconciliation incomplete after process restart." },
+		};
+	});
+}
+
+export interface ReconciliationStore {
+	readonly path: string | null;
+	readonly sessionId: string;
+	/** Serialize mutations; reload not required for single-process host (in-memory + write). */
+	transact(mutator: (records: DurableReconciliationRecord[]) => DurableReconciliationRecord[]): Promise<void>;
+	load(): Promise<DurableReconciliationRecord[]>;
+	/** Snapshot currently held in memory after last load/transact. */
+	snapshot(): DurableReconciliationRecord[];
+	delete(): Promise<void>;
+}
+
+export function createReconciliationStore(options: {
+	sessionFile: string | null | undefined;
+	sessionId: string;
+	fs?: ReconciliationStoreFs;
+	now?: () => number;
+}): ReconciliationStore {
+	const fileFs = options.fs ?? nodeFs;
+	const now = options.now ?? Date.now;
+	const sessionId = options.sessionId;
+	const filePath =
+		options.sessionFile && isSafeReconciliationSessionId(sessionId)
+			? reconciliationStorePath(options.sessionFile, sessionId)
+			: null;
+
+	let memory: DurableReconciliationRecord[] = [];
+	let chain: Promise<void> = Promise.resolve();
+
+	const writeAtomic = async (document: ReconciliationStoreDocument): Promise<void> => {
+		if (!filePath) return;
+		const directory = path.dirname(filePath);
+		await fileFs.mkdir(directory, { recursive: true, mode: 0o700 });
+		const temporary = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+		try {
+			await fileFs.writeFile(temporary, `${JSON.stringify(document)}\n`, { mode: 0o600 });
+			try {
+				const handle = await fileFs.open(temporary, "r+");
+				try {
+					await handle.sync();
+				} finally {
+					await handle.close();
+				}
+			} catch {
+				// fsync optional on some fs seams
+			}
+			await fileFs.rename(temporary, filePath);
+		} catch (error) {
+			await fileFs.unlink(temporary).catch(() => {});
+			throw Object.assign(error instanceof Error ? error : new Error("reconciliation persist failed"), {
+				code: "reconciliation_persist_failed",
+			});
+		}
+	};
+
+	const load = async (): Promise<DurableReconciliationRecord[]> => {
+		if (!filePath) {
+			memory = [];
+			return memory;
+		}
+		try {
+			const raw = await fileFs.readFile(filePath, "utf8");
+			const document = parseDocument(raw, sessionId);
+			memory = settleProcessRestart(document.records, now());
+			// Persist settled state so restart is sticky.
+			if (memory.some((r, i) => r !== document.records[i]))
+				await writeAtomic({ version: RECONCILIATION_STORE_VERSION, sessionId, records: memory });
+			return memory;
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+				memory = [];
+				return memory;
+			}
+			// Corrupt → quarantine
+			try {
+				await fileFs.rename(filePath, `${filePath}.corrupt.${now()}`);
+			} catch {
+				// ignore
+			}
+			memory = [];
+			return memory;
+		}
+	};
+
+	const transact = async (
+		mutator: (records: DurableReconciliationRecord[]) => DurableReconciliationRecord[],
+	): Promise<void> => {
+		const run = async () => {
+			const next = mutator(memory.map(r => ({ ...r })));
+			memory = next;
+			await writeAtomic({ version: RECONCILIATION_STORE_VERSION, sessionId, records: memory });
+		};
+		const pending = chain.then(run, run);
+		chain = pending.then(
+			() => undefined,
+			() => undefined,
+		);
+		await pending;
+	};
+
+	const deleteStore = async (): Promise<void> => {
+		memory = [];
+		if (!filePath) return;
+		await fileFs.unlink(filePath).catch(error => {
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+		});
+	};
+
+	return {
+		path: filePath,
+		sessionId,
+		transact,
+		load,
+		snapshot: () => memory.map(r => ({ ...r })),
+		delete: deleteStore,
+	};
+}

package/src/sdk/bus/telegram-cli.ts

@@ -21,7 +21,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { getAgentDir } from "@sayknow-cli/utils";
 import { tokenFingerprint } from "./config";
-import { type DaemonState, daemonPaths, isFreshLiveOwner } from "./telegram-daemon";
+import { isFreshLiveOwner, readOwnerFreshnessSnapshot } from "./telegram-daemon";
 import { runTelegramReferenceClient } from "./telegram-reference";
 
 interface CliArgs {
@@ -134,17 +134,9 @@ function pidAlive(pid: number): boolean {
 	}
 }
 
-function readDaemonState(): DaemonState | undefined {
-	try {
-		const raw = fs.readFileSync(daemonPaths(getAgentDir()).state, "utf8");
-		return JSON.parse(raw) as DaemonState;
-	} catch {
-		return undefined;
-	}
-}
-
-function activeDaemonOwnsToken(input: { botToken: string; chatId: string }): boolean {
-	const state = readDaemonState();
+async function activeDaemonOwnsToken(input: { botToken: string; chatId: string }): Promise<boolean> {
+	const snapshot = await readOwnerFreshnessSnapshot({ settings: { getAgentDir } as never });
+	const state = snapshot.state;
 	if (!state) return false;
 	return isFreshLiveOwner({
 		state,
@@ -152,6 +144,7 @@ function activeDaemonOwnsToken(input: { botToken: string; chatId: string }): boo
 		tokenFingerprint: tokenFingerprint(input.botToken),
 		chatId: input.chatId,
 		pidAlive,
+		effectiveHeartbeatAt: snapshot.effectiveHeartbeatAt,
 	});
 }
 
@@ -176,7 +169,7 @@ async function main(): Promise<void> {
 	}
 
 	const chatId = args.chatId ?? process.env.SKC_TG_CHAT_ID ?? (await resolveChatId(botToken, apiBase));
-	if (!args.force && activeDaemonOwnsToken({ botToken, chatId })) {
+	if (!args.force && (await activeDaemonOwnsToken({ botToken, chatId }))) {
 		process.stderr.write(
 			"an active skc notifications daemon already owns this bot token; running a second poller will cause Telegram 409 conflicts. Re-run with --force to override.\n",
 		);

package/src/sdk/bus/telegram-daemon-cli.ts

@@ -14,6 +14,7 @@ import { daemonPaths, HEARTBEAT_TTL_MS } from "./daemon-paths";
 import {
 	type DaemonState,
 	readDaemonState,
+	readOwnerFreshnessSnapshot,
 	type TelegramDaemonOptions,
 	TelegramNotificationDaemon,
 } from "./telegram-daemon";
@@ -254,15 +255,19 @@ export async function runDaemonInternal(argv: string[], deps: RunDaemonInternalD
 		if (!watchdogActive || watchdogTickInFlight || stopRequested) return;
 		watchdogTickInFlight = true;
 		try {
-			const state = await readState(settings as Settings);
+			const snapshot = deps.readDaemonState
+				? { state: await readState(settings as Settings), effectiveHeartbeatAt: undefined }
+				: await readOwnerFreshnessSnapshot({ settings: settings as Settings });
+			const state = snapshot.state;
+			const heartbeatAt = snapshot.effectiveHeartbeatAt ?? state?.heartbeatAt;
 			if (!watchdogActive || !state) return;
 			if (state.ownerId !== ownerId) {
 				stopRequested = true;
 				daemon.requestStop("stop");
 				return;
 			}
-			if (lastHeartbeatAt === undefined || state.heartbeatAt !== lastHeartbeatAt) {
-				lastHeartbeatAt = state.heartbeatAt;
+			if (lastHeartbeatAt === undefined || heartbeatAt !== lastHeartbeatAt) {
+				lastHeartbeatAt = heartbeatAt;
 				stalledSince = now();
 				return;
 			}

package/src/sdk/bus/telegram-daemon-contract.ts

@@ -7,12 +7,9 @@
 export const NOTIFICATION_PROTOCOL_VERSION = 3;
 
 /**
- * Operational generation the current daemon build speaks. Decoupled from
- * {@link NOTIFICATION_PROTOCOL_VERSION} (#2304): additive `tool_activity` /
- * `reasoning_summary` frames do not bump the wire protocol version, but a
- * freshly-upgraded host must still recognize an older, still-live daemon that
- * predates capability-gated frame enforcement and trigger a reload. Bump this
- * on every daemon-behavior change independent of the wire version.
+ * Guarded behavior-inventory version for the current daemon build. Bump this
+ * on every guarded daemon-behavior change independent of the wire version; it
+ * does not force a live daemon reload by itself.
  * The current development baseline already includes #2299's generation 4,
  * incarnation fencing in generation 5, owner-lock authority in generation 6,
  * identity-atomic transition markers in generation 7, stable signaling plus
@@ -21,7 +18,35 @@ export const NOTIFICATION_PROTOCOL_VERSION = 3;
  * confirmed-dead owner's lock in generation 10, legacy stopped-tombstone
  * reclamation in generation 11, force-escalated SIGKILL of an unresponsive
  * older-generation owner during automatic generation-upgrade reload in
- * generation 12, and restored macOS daemon signaling (kill(2) with a start-time
- * incarnation recheck, replacing the darwin no-op) in generation 13.
+ * generation 12, restored macOS daemon signaling (kill(2) with a start-time
+ * incarnation recheck, replacing the darwin no-op) in generation 13, retained
+ * legacy stopped-lock reclamation in generation 14, Windows expected-identity
+ * ACL verification and repair in generation 15, identity-fenced stale endpoint
+ * startup recovery in generation 16, Telegram topic recovery authority fencing
+ * in generation 17, fail-closed blank-token validation plus lifecycle-startup
+ * stop fencing in generation 18, recommended ask metadata rendering in
+ * generation 19, authoritative terminal session-close delivery and cleanup
+ * fencing, attested generation-bearing pre-incarnation owner handoff in
+ * generation 20, guarded modern generation-absent predecessor signaling in
+ * generation 21, dead Windows v0.10 owner replacement in generation 22, and
+ * retained native cleanup authority revalidation in generation 23, and typed
+ * retained exact-unlink cleanup authority acceptance (concrete detached
+ * quarantine plus proven canonical absence) in generation 24.
+ * Generation 25 adds startup dead-root prune + leak-artifact self-heal
+ * on TelegramNotificationDaemon.run (#2958). Generation 26 adds bounded reload
+ * cooldown and lazy Telegram topic lifecycle safeguards (#2956, #2960, #2984).
+ * Generation 27 refreshes retained native path and process authority semantics.
+ * Generation 28 rejects special files before retained native authority opens.
+ * Generation 29 adds serving-epoch compatibility, sidecar heartbeat, root GC,
+ * and Bot API cooldown structural fixes (#2956, #2960, #3048).
+ * Generation 30 adds opt-in tool activity delivery, closed lifecycle phases,
+ * and capability-versioned mixed-host compatibility.
  */
-export const DAEMON_GENERATION = 13;
+export const DAEMON_GENERATION = 30;
+
+/**
+ * Serving-compatibility boundary for daemon lifecycle requests. Epoch 1 covers
+ * all builds published before this field existed; epoch 2 covered generation 29;
+ * bump this to force serving convergence and reload of compatible live predecessors.
+ */
+export const SERVING_EPOCH = 3;