@keyou007/agent-bot 0.1.1 → 0.1.3

package/src/feishu/transport.ts

@@ -1,24 +1,15 @@
 import type { AppConfig } from "../config/schema.js";
 
-export type FeishuTransportMode = "sdk" | "console";
-
 type FeishuTransportConfig = Pick<
   AppConfig["feishu"],
-  "transport" | "appId" | "appSecret" | "useConsoleWhenMissingCredentials"
+  "appId" | "appSecret"
 >;
 
-export function resolveFeishuTransport(config: FeishuTransportConfig): FeishuTransportMode {
-  if (config.transport === "console") {
-    return "console";
-  }
-
-  const hasCredentials = Boolean(config.appId && config.appSecret);
-  if (config.transport === "sdk" || !config.useConsoleWhenMissingCredentials) {
-    if (!hasCredentials) {
-      throw new Error("Feishu appId/appSecret are required.");
-    }
-    return "sdk";
+export function requireServerFeishuTransport(config: FeishuTransportConfig): "sdk" {
+  if (!config.appId || !config.appSecret) {
+    throw new Error(
+      "飞书机器人尚未配置。请先运行 agent-bot init 完成初始化；仅需本地调试时请使用 agent-bot console。",
+    );
   }
-
-  return hasCredentials ? "sdk" : "console";
+  return "sdk";
 }

package/src/index.ts

@@ -15,7 +15,7 @@ import { ConsoleFeishuClient } from "./feishu/ConsoleFeishuClient.js";
 import { FeishuConnector } from "./feishu/FeishuConnector.js";
 import { FeishuMessageClient } from "./feishu/FeishuMessageClient.js";
 import { FeishuTurnPresenter } from "./feishu/FeishuTurnPresenter.js";
-import { resolveFeishuTransport } from "./feishu/transport.js";
+import { requireServerFeishuTransport } from "./feishu/transport.js";
 import { createLogger } from "./logging/logger.js";
 import { OutboundRouter, type OutboundRoute } from "./presentation/OutboundRouter.js";
 import { ProxySessionController } from "./proxy/ProxySessionController.js";
@@ -29,6 +29,11 @@ import { STOP_EXIT_CODE } from "./supervision/restartPolicy.js";
 import { replacementSupervisorEnvironment } from "./supervision/replacementSupervisor.js";
 import { SafeRestartScheduler } from "./supervision/SafeRestartScheduler.js";
 import { SafeRestartNotifier } from "./supervision/SafeRestartNotifier.js";
+import {
+  nodeDiagnosticReportArguments,
+  prepareCrashReportDirectory,
+  resolveSupervisorDiagnosticsPaths,
+} from "./supervision/SupervisorDiagnostics.js";
 
 const processStartedAt = new Date();
 const supervised = process.env.AGENT_BOT_SUPERVISED === "1";
@@ -36,6 +41,7 @@ const startupReason = process.env.AGENT_BOT_RESTART_REASON?.trim()
   || (supervised ? "Supervisor 启动" : "直接启动");
 const consoleOnly = process.env.AGENT_BOT_CONSOLE_ONLY === "1";
 const config = loadConfig();
+const transport = consoleOnly ? "console" : requireServerFeishuTransport(config.feishu);
 const logger = createLogger(config);
 const store = new StateStore(config.storage.sqlitePath);
 
@@ -52,13 +58,13 @@ const codexProcessManager = new CodexProcessManager(
 const codexRuntime = new CodexRuntime(codexProcessManager, logger);
 const runtimes = new AgentRuntimeRegistry({ acp: acpRuntime, codex: codexRuntime });
 
-const transport = consoleOnly ? "console" : resolveFeishuTransport(config.feishu);
 const routes: OutboundRoute[] = [];
 let feishuConnector: FeishuConnector | undefined;
 let consoleConnector: ConsoleConnector | undefined;
 let startupNotifier: StartupNotifier | undefined;
 let safeRestartNotifier: SafeRestartNotifier | undefined;
 let controlServer: LocalControlServer | undefined;
+let serverReady = false;
 
 const feishuOutbound = transport === "sdk" ? new FeishuMessageClient(config, logger) : undefined;
 if (feishuOutbound) {
@@ -77,6 +83,7 @@ if (feishuOutbound) {
     defaultAgentTitle: defaultAgent?.title ?? defaultAgentName,
     cwd: path.resolve(config.defaults.cwd),
     workspaceKind: defaultAgent?.kind === "codex" ? "projectless" : "project",
+    defaultUserOpenId: config.feishu.userOpenId,
   }, metadataHydrator);
   safeRestartNotifier = new SafeRestartNotifier(store, feishuOutbound, renderer, logger);
 }
@@ -95,16 +102,17 @@ if (routes.length === 0) throw new Error("Neither Feishu nor console input is en
 const outbound = new OutboundRouter(routes);
 let shuttingDown = false;
 let restartRequested = false;
-const controller = new ProxySessionController(config, store, runtimes, outbound, logger, {
-  supervised,
-  restart: requestRestart,
-});
 const safeRestart = new SafeRestartScheduler({
   readActivity: () => store.getServerActivityState(),
   onReady: (reason) => initiateRestart(reason),
   onStatus: (status) => safeRestartNotifier?.update(status),
   onStatusError: (error) => logger.warn({ error }, "Failed to publish safe restart status."),
 });
+const controller = new ProxySessionController(config, store, runtimes, outbound, logger, {
+  supervised,
+  restart: requestRestart,
+  cancelSafeRestart: (scheduleId) => safeRestart.cancelScheduled(scheduleId),
+});
 
 if (feishuOutbound) feishuConnector = new FeishuConnector(config, controller, logger);
 if (consoleEnabled) consoleConnector = new ConsoleConnector(controller, logger);
@@ -123,10 +131,18 @@ const startControlServer = async (): Promise<void> => {
 };
 
 if (feishuConnector && startupNotifier) {
-  await startFeishu(feishuConnector, startupNotifier, processStartedAt, startupReason, startControlServer);
+  await startFeishu(
+    feishuConnector,
+    startupNotifier,
+    processStartedAt,
+    startupReason,
+    startControlServer,
+    () => { serverReady = true; },
+  );
 } else {
   await startControlServer();
   await feishuConnector?.start();
+  serverReady = true;
 }
 consoleConnector?.start();
 
@@ -156,6 +172,8 @@ async function handleControlRequest(request: ControlRequest): Promise<ControlRes
       return {
         ok: true,
         data: {
+          ready: serverReady,
+          phase: serverReady ? "ready" : "connecting_feishu",
           pid: process.pid,
           startedAt: processStartedAt.toISOString(),
           supervised,
@@ -213,7 +231,12 @@ async function shutdown(exitCode: number, restartReason?: string): Promise<void>
 
 function startReplacementSupervisor(restartReason: string): void {
   const supervisorEntry = fileURLToPath(new URL("./supervisor.js", import.meta.url));
-  const supervisor = spawn(process.execPath, [supervisorEntry], {
+  const reportDirectory = resolveSupervisorDiagnosticsPaths(config).crashReportDirectory;
+  prepareCrashReportDirectory(reportDirectory);
+  const supervisor = spawn(process.execPath, [
+    ...nodeDiagnosticReportArguments(reportDirectory),
+    supervisorEntry,
+  ], {
     cwd: process.cwd(),
     detached: true,
     windowsHide: true,

package/src/proxy/ProxySessionController.ts

@@ -123,6 +123,7 @@ interface CreatedFeishuGroupContext {
 export interface ProxyLifecycle {
   supervised?: boolean;
   restart(contextKey: string): Promise<void>;
+  cancelSafeRestart?(scheduleId: number): Promise<boolean>;
 }
 
 export type ShellCommandExecutor = (command: string, cwd: string) => Promise<ShellCommandResult>;
@@ -176,9 +177,8 @@ export class ProxySessionController {
   }
 
   async onMessage(message: IncomingMessage): Promise<void> {
-    if (message.chatId && message.chatType) {
-      this.store.recordChatContext(baseChatContextKey(message.contextKey), message.chatType);
-    }
+    // The durable deduplication claim is the only operation allowed before acknowledgement.
+    // It prevents event retries from adding duplicate reactions.
     if (!this.store.claimInboundEvent(message.messageId, "message")) return;
     try {
       const reactionId = await this.outbound.addReaction(
@@ -195,6 +195,9 @@ export class ProxySessionController {
         "Failed to acknowledge the incoming Feishu message with a reaction.",
       );
     }
+    if (message.chatId && message.chatType) {
+      this.store.recordChatContext(baseChatContextKey(message.contextKey), message.chatType);
+    }
     const replyTarget = message.replyInThread
       ? { messageId: message.messageId, replyInThread: true as const }
       : undefined;
@@ -323,6 +326,18 @@ export class ProxySessionController {
           await this.cancelSession(this.requireSession(contextKey, sessionId));
         } else if (kind === "queued_prompt_cancel") {
           await this.cancelQueuedPrompt(scopedAction);
+        } else if (kind === "safe_restart_cancel") {
+          const scheduleId = Number(scopedAction.value.scheduleId);
+          if (!Number.isSafeInteger(scheduleId) || scheduleId <= 0) {
+            throw new Error("安全重启卡片无效，请使用最新的状态卡片。");
+          }
+          if (!this.lifecycle?.cancelSafeRestart) {
+            throw new Error("当前运行方式不支持取消安全重启。");
+          }
+          const cancelled = await this.lifecycle.cancelSafeRestart(scheduleId);
+          if (!cancelled) {
+            await this.outbound.sendText(contextKey, "该安全重启计划已失效，请查看最新状态卡片。");
+          }
         } else if (kind === "session_more") {
           await this.refreshSessionsCardFromAction(scopedAction, undefined, true);
         } else if (kind === "session_switch") {

package/src/startup/StartupNotifier.ts

@@ -2,19 +2,25 @@ import type { Logger } from "pino";
 import { detectProjectlessWorkspace } from "../codex/ProjectlessWorkspace.js";
 import { CardRenderer } from "../feishu/CardRenderer.js";
 import type { FeishuOutbound } from "../feishu/types.js";
-import type { SessionRecord, StateStore } from "../state/StateStore.js";
+import type { SessionRecord, StateStore, UserContextRecord } from "../state/StateStore.js";
 
 export interface StartupNotificationOptions {
   defaultAgentName: string;
   defaultAgentTitle: string;
   cwd: string;
   workspaceKind?: "project" | "projectless";
+  defaultUserOpenId?: string;
 }
 
 export interface StartupTaskMetadataHydrator {
   hydrate(session: SessionRecord): Promise<SessionRecord>;
 }
 
+interface StartupNotificationTarget {
+  contextKey: string;
+  context?: UserContextRecord;
+}
+
 export class StartupNotifier {
   constructor(
     private readonly store: StateStore,
@@ -26,7 +32,7 @@ export class StartupNotifier {
   ) {}
 
   async notify(startedAt: Date, restartReason: string): Promise<void> {
-    let targets;
+    let targets: StartupNotificationTarget[];
     try {
       const activeGroupSince = new Date(startedAt.getTime() - 3 * 60 * 1_000);
       const chats = [
@@ -40,10 +46,16 @@ export class StartupNotifier {
       }));
     } catch (error) {
       this.logger.warn({ error }, "Failed to load startup notification targets.");
-      return;
+      throw new Error("Failed to load startup notification targets.", { cause: error });
     }
 
-    await Promise.all(targets.map(async ({ contextKey, context }) => {
+    if (targets.length === 0) {
+      const defaultUserOpenId = this.options.defaultUserOpenId?.trim();
+      if (!defaultUserOpenId) return;
+      targets = [{ contextKey: `open_id:${defaultUserOpenId}` }];
+    }
+
+    const deliveries = await Promise.all(targets.map(async ({ contextKey, context }) => {
       let session = context?.currentSessionId ? this.store.getSession(context.currentSessionId) : undefined;
       if (session && this.metadataHydrator) {
         try {
@@ -81,12 +93,17 @@ export class StartupNotifier {
       });
       try {
         await this.outbound.sendInteractiveCard(contextKey, card);
+        return true;
       } catch (error) {
         this.logger.warn(
           { error, contextKey },
           "Failed to send startup status notification.",
         );
+        return false;
       }
     }));
+    if (deliveries.length > 0 && !deliveries.some(Boolean)) {
+      throw new Error("Failed to send any startup status notification.");
+    }
   }
 }

package/src/startup/startFeishu.ts

@@ -12,8 +12,10 @@ export async function startFeishu(
   startedAt: Date,
   restartReason: string,
   prepare?: () => Promise<void>,
+  onConnected?: () => void,
 ): Promise<void> {
   await prepare?.();
   await connector.start();
   await notifier.notify(startedAt, restartReason);
+  onConnected?.();
 }

package/src/supervision/SafeRestartNotifier.ts

@@ -14,6 +14,7 @@ export class SafeRestartNotifier {
   private readonly messageIds = new Map<string, string>();
   private readonly cardHashes = new Map<string, string>();
   private activeScheduleId?: number;
+  private terminalScheduleId?: number;
   private pendingInitialStatus?: SafeRestartStatus;
   private initialCardTimer?: NodeJS.Timeout;
   private queue = Promise.resolve();
@@ -27,13 +28,24 @@ export class SafeRestartNotifier {
   ) {}
 
   update(status: SafeRestartStatus): Promise<void> {
+    if (this.terminalScheduleId !== undefined && status.scheduleId <= this.terminalScheduleId) {
+      if (status.phase !== "cancelled") return Promise.resolve();
+    }
+    if (this.activeScheduleId !== undefined && status.scheduleId < this.activeScheduleId) {
+      return Promise.resolve();
+    }
+    if (status.phase === "cancelled") {
+      this.terminalScheduleId = Math.max(this.terminalScheduleId ?? 0, status.scheduleId);
+    }
     if (this.activeScheduleId !== status.scheduleId) {
       this.activeScheduleId = status.scheduleId;
       this.messageIds.clear();
       this.cardHashes.clear();
       this.clearInitialCardTimer();
       this.pendingInitialStatus = status;
-      const delayMs = this.options.initialCardDelayMs ?? DEFAULT_INITIAL_CARD_DELAY_MS;
+      const delayMs = status.phase === "cancelled"
+        ? 0
+        : this.options.initialCardDelayMs ?? DEFAULT_INITIAL_CARD_DELAY_MS;
       if (delayMs <= 0) return this.publishPendingInitialStatus();
       this.initialCardTimer = setTimeout(() => {
         this.initialCardTimer = undefined;
@@ -79,13 +91,16 @@ export class SafeRestartNotifier {
   private async publish(status: SafeRestartStatus): Promise<void> {
     const targets = this.store.listChatContexts("p2p");
     if (targets.length === 0) return;
-    const waitingTasks = this.store.listAllSessions()
-      .filter((session) => session.status === "running" || this.store.countQueuedPrompts(session.localSessionId) > 0)
-      .map((session) => ({
-        id: session.remoteSessionId ?? session.localSessionId,
-        title: session.title,
-      }));
+    const waitingTasks = status.phase === "cancelled"
+      ? []
+      : this.store.listAllSessions()
+        .filter((session) => session.status === "running" || this.store.countQueuedPrompts(session.localSessionId) > 0)
+        .map((session) => ({
+          id: session.remoteSessionId ?? session.localSessionId,
+          title: session.title,
+        }));
     const card = this.renderer.renderSafeRestartStatus({
+      scheduleId: status.scheduleId,
       reason: status.reason,
       phase: status.phase,
       remainingMs: status.remainingMs,

package/src/supervision/SafeRestartScheduler.ts

@@ -4,7 +4,12 @@ export interface ServerActivityState {
   latestInboundAt?: string;
 }
 
-export type SafeRestartPhase = "waiting_tasks" | "waiting_delivery" | "countdown" | "restarting";
+export type SafeRestartPhase =
+  | "waiting_tasks"
+  | "waiting_delivery"
+  | "countdown"
+  | "restarting"
+  | "cancelled";
 
 export interface SafeRestartStatus {
   scheduleId: number;
@@ -56,6 +61,24 @@ export class SafeRestartScheduler {
   }
 
   cancel(): void {
+    this.clear();
+  }
+
+  async cancelScheduled(expectedScheduleId: number): Promise<boolean> {
+    const reason = this.reason;
+    if (!reason || this.scheduleId !== expectedScheduleId) return false;
+    const activity = this.options.readActivity();
+    this.clear();
+    await this.emitStatus({
+      scheduleId: expectedScheduleId,
+      reason,
+      phase: "cancelled",
+      activity,
+    });
+    return true;
+  }
+
+  private clear(): void {
     if (this.timer) clearInterval(this.timer);
     this.timer = undefined;
     this.reason = undefined;
@@ -117,8 +140,9 @@ export class SafeRestartScheduler {
       }
       return;
     }
-    await this.emitStatus({ scheduleId: this.scheduleId, reason, phase: "restarting", activity: confirmed, remainingMs: 0 });
-    this.cancel();
+    const scheduleId = this.scheduleId;
+    this.clear();
+    await this.emitStatus({ scheduleId, reason, phase: "restarting", activity: confirmed, remainingMs: 0 });
     await this.options.onReady(reason);
   }
 

package/src/supervision/SupervisorDiagnostics.ts

@@ -0,0 +1,268 @@
+import fs from "node:fs";
+import path from "node:path";
+import type { AppConfig } from "../config/schema.js";
+
+const MAX_LOG_BYTES = 10 * 1024 * 1024;
+const LOG_BACKUP_COUNT = 3;
+
+export interface SupervisorDiagnosticsPaths {
+  supervisorLogPath: string;
+  workerStderrPath: string;
+  crashReportDirectory: string;
+  lastCrashPath: string;
+}
+
+export interface WorkerCrashContext {
+  workerPid?: number;
+  exitCode: number | null;
+  signal: NodeJS.Signals | null;
+  startedAt: string;
+  exitedAt: string;
+  uptimeMs: number;
+  consecutiveFailures: number;
+  restartDelayMs: number;
+}
+
+export interface WorkerCrashRecord extends WorkerCrashContext {
+  version: 1;
+  supervisorPid: number;
+  nodeVersion: string;
+  executablePath: string;
+  cwd: string;
+  supervisorLogPath: string;
+  workerStderrPath: string;
+  crashReportDirectory: string;
+  diagnosticReports: string[];
+}
+
+type ExtendedProcessReport = typeof process.report & {
+  excludeEnv?: boolean;
+  excludeNetwork?: boolean;
+};
+
+export class SupervisorDiagnostics {
+  readonly paths: SupervisorDiagnosticsPaths;
+
+  constructor(config: Pick<AppConfig, "logging" | "storage">) {
+    this.paths = resolveSupervisorDiagnosticsPaths(config);
+  }
+
+  initialize(): void {
+    try {
+      ensurePrivateDirectory(path.dirname(this.paths.supervisorLogPath));
+      ensurePrivateDirectory(this.paths.crashReportDirectory);
+      rotateLogFile(this.paths.supervisorLogPath);
+      rotateLogFile(this.paths.workerStderrPath);
+      this.configureCurrentProcessReports();
+      this.writeEvent("diagnostics_initialized", {
+        nodeVersion: process.versions.node,
+        supervisorLogPath: this.paths.supervisorLogPath,
+        workerStderrPath: this.paths.workerStderrPath,
+        crashReportDirectory: this.paths.crashReportDirectory,
+      });
+    } catch (error) {
+      writeFallbackDiagnostic("initialize_failed", error);
+    }
+  }
+
+  writeEvent(event: string, data: Record<string, unknown> = {}): void {
+    const line = `${JSON.stringify({
+      component: "agent-bot-supervisor",
+      event,
+      time: new Date().toISOString(),
+      ...data,
+    })}\n`;
+    try {
+      fs.appendFileSync(this.paths.supervisorLogPath, line, { encoding: "utf8", mode: 0o600 });
+      restrictFilePermissions(this.paths.supervisorLogPath);
+    } catch (error) {
+      writeFallbackDiagnostic(event, error);
+    }
+  }
+
+  openWorkerStderr(): number | "ignore" {
+    try {
+      rotateLogFile(this.paths.workerStderrPath);
+      fs.appendFileSync(
+        this.paths.workerStderrPath,
+        `${JSON.stringify({ event: "worker_started", time: new Date().toISOString() })}\n`,
+        { encoding: "utf8", mode: 0o600 },
+      );
+      restrictFilePermissions(this.paths.workerStderrPath);
+      return fs.openSync(this.paths.workerStderrPath, "a", 0o600);
+    } catch (error) {
+      this.writeEvent("worker_stderr_open_failed", { error: errorMessage(error) });
+      return "ignore";
+    }
+  }
+
+  closeWorkerStderr(target: number | "ignore"): void {
+    if (typeof target !== "number") return;
+    try {
+      fs.closeSync(target);
+    } catch (error) {
+      this.writeEvent("worker_stderr_close_failed", { error: errorMessage(error) });
+    }
+  }
+
+  recordCrash(context: WorkerCrashContext): WorkerCrashRecord | undefined {
+    try {
+      const record: WorkerCrashRecord = {
+        version: 1,
+        ...context,
+        supervisorPid: process.pid,
+        nodeVersion: process.versions.node,
+        executablePath: process.execPath,
+        cwd: process.cwd(),
+        supervisorLogPath: this.paths.supervisorLogPath,
+        workerStderrPath: this.paths.workerStderrPath,
+        crashReportDirectory: this.paths.crashReportDirectory,
+        diagnosticReports: findDiagnosticReports(
+          this.paths.crashReportDirectory,
+          context.workerPid,
+          Date.parse(context.startedAt),
+        ),
+      };
+      const crashPath = path.join(
+        this.paths.crashReportDirectory,
+        crashRecordFilename(context.exitedAt, context.workerPid),
+      );
+      writePrivateJson(crashPath, record);
+      writePrivateJson(this.paths.lastCrashPath, record);
+      this.writeEvent("crash_context_saved", {
+        crashPath,
+        lastCrashPath: this.paths.lastCrashPath,
+        diagnosticReports: record.diagnosticReports,
+      });
+      return record;
+    } catch (error) {
+      this.writeEvent("crash_context_save_failed", { error: errorMessage(error) });
+      return undefined;
+    }
+  }
+
+  private configureCurrentProcessReports(): void {
+    const report = process.report as ExtendedProcessReport;
+    report.directory = this.paths.crashReportDirectory;
+    report.reportOnFatalError = true;
+    report.reportOnUncaughtException = true;
+    if ("excludeEnv" in report) report.excludeEnv = true;
+    if ("excludeNetwork" in report) report.excludeNetwork = true;
+  }
+}
+
+export function resolveSupervisorDiagnosticsPaths(
+  config: Pick<AppConfig, "logging" | "storage">,
+): SupervisorDiagnosticsPaths {
+  const logDirectory = path.dirname(config.logging.path);
+  const dataDirectory = path.dirname(config.storage.sqlitePath);
+  return {
+    supervisorLogPath: path.join(logDirectory, "supervisor.log"),
+    workerStderrPath: path.join(logDirectory, "worker.stderr.log"),
+    crashReportDirectory: path.join(dataDirectory, "crash-reports"),
+    lastCrashPath: path.join(dataDirectory, "last-crash.json"),
+  };
+}
+
+export function nodeDiagnosticReportArguments(
+  reportDirectory: string,
+  allowedFlags: ReadonlySet<string> = process.allowedNodeEnvironmentFlags,
+): string[] {
+  const args = [
+    "--report-on-fatalerror",
+    "--report-uncaught-exception",
+    `--report-directory=${reportDirectory}`,
+  ];
+  if (allowedFlags.has("--report-exclude-env")) args.push("--report-exclude-env");
+  if (allowedFlags.has("--report-exclude-network")) args.push("--report-exclude-network");
+  return args;
+}
+
+export function prepareCrashReportDirectory(reportDirectory: string): boolean {
+  try {
+    ensurePrivateDirectory(reportDirectory);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function ensurePrivateDirectory(directoryPath: string): void {
+  fs.mkdirSync(directoryPath, { recursive: true, mode: 0o700 });
+  try {
+    fs.chmodSync(directoryPath, 0o700);
+  } catch {
+    // Windows and some mounted filesystems do not implement POSIX modes.
+  }
+}
+
+function rotateLogFile(filePath: string): void {
+  const size = fs.statSync(filePath, { throwIfNoEntry: false })?.size ?? 0;
+  if (size < MAX_LOG_BYTES) return;
+  for (let index = LOG_BACKUP_COUNT; index >= 1; index -= 1) {
+    const source = index === 1 ? filePath : `${filePath}.${index - 1}`;
+    const target = `${filePath}.${index}`;
+    if (!fs.existsSync(source)) continue;
+    fs.rmSync(target, { force: true });
+    fs.renameSync(source, target);
+  }
+}
+
+function findDiagnosticReports(
+  reportDirectory: string,
+  workerPid: number | undefined,
+  startedAtMs: number,
+): string[] {
+  if (!fs.existsSync(reportDirectory)) return [];
+  const pidToken = workerPid === undefined ? undefined : `.${workerPid}.`;
+  return fs.readdirSync(reportDirectory, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && /^report\..+\.json$/i.test(entry.name))
+    .filter((entry) => {
+      if (pidToken && entry.name.includes(pidToken)) return true;
+      const modifiedAt = fs.statSync(path.join(reportDirectory, entry.name)).mtimeMs;
+      return workerPid === undefined && modifiedAt >= startedAtMs - 1_000;
+    })
+    .map((entry) => path.join(reportDirectory, entry.name))
+    .sort();
+}
+
+function crashRecordFilename(exitedAt: string, workerPid: number | undefined): string {
+  const timestamp = exitedAt.replace(/\D/g, "");
+  return `crash-${timestamp}-${workerPid ?? "unknown"}.json`;
+}
+
+function writePrivateJson(filePath: string, value: unknown): void {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, {
+    encoding: "utf8",
+    mode: 0o600,
+  });
+  restrictFilePermissions(filePath);
+}
+
+function restrictFilePermissions(filePath: string): void {
+  try {
+    fs.chmodSync(filePath, 0o600);
+  } catch {
+    // Windows and some mounted filesystems do not implement POSIX modes.
+  }
+}
+
+function writeFallbackDiagnostic(event: string, error: unknown): void {
+  try {
+    process.stderr.write(
+      `${JSON.stringify({
+        component: "agent-bot-supervisor",
+        event,
+        time: new Date().toISOString(),
+        error: errorMessage(error),
+      })}\n`,
+    );
+  } catch {
+    // Diagnostics must never prevent the supervisor from keeping the worker alive.
+  }
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}