agor-live 0.18.0 → 0.19.1

package/dist/daemon/setup/index.js

@@ -300,17 +300,46 @@ async function safeUnlink(path) {
 }
 async function runFirstRunAdminBootstrap(db, options = {}) {
   const credentialsPath = getAdminCredentialsPath(options.credentialsBaseDir);
+  const envPassword = process.env.AGOR_ADMIN_PASSWORD;
   let credentialsWritten = false;
   const result = await bootstrapFirstRunAdmin(db, async () => {
+    if (envPassword && envPassword.length > 0) {
+      return await createUser(db, {
+        email: BOOTSTRAP_ADMIN_EMAIL,
+        password: envPassword,
+        name: "Admin",
+        role: "superadmin",
+        unix_username: "admin",
+        must_change_password: true
+      });
+    }
     const password = generateAdminPassword();
-    await writeCredentialsExclusive(credentialsPath, BOOTSTRAP_ADMIN_EMAIL, password);
+    try {
+      await writeCredentialsExclusive(credentialsPath, BOOTSTRAP_ADMIN_EMAIL, password);
+    } catch (err) {
+      const code = err.code;
+      if (code === "EEXIST") throw err;
+      throw new Error(
+        [
+          `Failed to write admin credentials file at ${credentialsPath}.`,
+          "",
+          "Set the AGOR_ADMIN_PASSWORD environment variable to skip the",
+          "credentials file entirely (the password you provide is used to",
+          "create the bootstrap admin), or make the parent directory",
+          "writable so the daemon can persist a generated password.",
+          "",
+          `Underlying error: ${err instanceof Error ? err.message : String(err)}`
+        ].join("\n")
+      );
+    }
     credentialsWritten = true;
     try {
       return await createUser(db, {
         email: BOOTSTRAP_ADMIN_EMAIL,
         password,
         name: "Admin",
-        role: "admin",
+        role: "superadmin",
+        unix_username: "admin",
         // Forces the operator to set their own password after first login.
         // Without this the printed/persisted cleartext stays valid forever.
         must_change_password: true
@@ -327,15 +356,19 @@ async function runFirstRunAdminBootstrap(db, options = {}) {
   };
 }
 function logFirstRunAdminBootstrap(result) {
-  if (result.createdAdmin && result.credentialsPath && result.admin) {
+  if (result.createdAdmin && result.admin) {
     process.stderr.write("\n");
     process.stderr.write("================================================================\n");
     process.stderr.write("\u{1F510}  First-run admin user created\n");
     process.stderr.write("----------------------------------------------------------------\n");
     process.stderr.write(`    Email:     ${result.admin.email}
 `);
-    process.stderr.write(`    Password:  see ${result.credentialsPath} (mode 0600)
+    if (result.credentialsPath) {
+      process.stderr.write(`    Password:  see ${result.credentialsPath} (mode 0600)
 `);
+    } else {
+      process.stderr.write("    Password:  set via the AGOR_ADMIN_PASSWORD env var\n");
+    }
     process.stderr.write("\n");
     process.stderr.write("    You will be prompted to change the password on first login.\n");
     process.stderr.write("================================================================\n");
@@ -399,6 +432,7 @@ async function initializeDatabase(dbPath) {
 }
 
 // src/setup/socketio.ts
+import { shortId } from "@agor/core/db";
 import jwt from "jsonwebtoken";
 function getSocketAuthState(socket) {
   const s = socket;
@@ -502,9 +536,7 @@ function createSocketIOConfig(app, options) {
         }
         const user = await app.service("users").get(decoded.sub);
         socket.feathers = { user };
-        console.log(
-          `\u{1F510} WebSocket authenticated: ${socket.id} (user: ${user.user_id.substring(0, 8)})`
-        );
+        console.log(`\u{1F510} WebSocket authenticated: ${socket.id} (user: ${shortId(user.user_id)})`);
         next();
       } catch (error) {
         console.error(`\u274C WebSocket authentication failed for ${socket.id}:`, error);
@@ -515,7 +547,7 @@ function createSocketIOConfig(app, options) {
       activeConnections++;
       const user = socket.feathers?.user;
       console.log(
-        `\u{1F50C} Socket.io connection established: ${socket.id} (user: ${user ? user.user_id.substring(0, 8) : "unknown"}, total: ${activeConnections})`
+        `\u{1F50C} Socket.io connection established: ${socket.id} (user: ${user ? shortId(user.user_id) : "unknown"}, total: ${activeConnections})`
       );
       if (buildInfo) {
         socket.emit("server-info", {
@@ -526,7 +558,7 @@ function createSocketIOConfig(app, options) {
       if (user?.user_id) {
         socket.join(userRoomName(user.user_id));
         console.log(
-          `\u{1F3E0} Socket ${socket.id} joined user room at connection: user:${user.user_id.substring(0, 8)}`
+          `\u{1F3E0} Socket ${socket.id} joined user room at connection: user:${shortId(user.user_id)}`
         );
       }
       setTimeout(() => {
@@ -578,7 +610,7 @@ function createSocketIOConfig(app, options) {
         if (typeof payloadUserId !== "string" || payloadUserId !== auth.userId) {
           rejectTerminal(
             event,
-            `payload userId (${String(payloadUserId).slice(0, 8)}\u2026) does not match authed userId (${auth.userId.slice(0, 8)}\u2026)`
+            `payload userId (${shortId(String(payloadUserId))}\u2026) does not match authed userId (${shortId(auth.userId)}\u2026)`
           );
           return null;
         }
@@ -602,7 +634,7 @@ function createSocketIOConfig(app, options) {
         if (!auth.isService && auth.userId !== target) {
           rejectTerminal(
             "join",
-            `user ${auth.userId?.slice(0, 8)}\u2026 tried to join ${target.slice(0, 8)}\u2026's channel`
+            `user ${auth.userId ? shortId(auth.userId) : "unknown"}\u2026 tried to join ${shortId(target)}\u2026's channel`
           );
           return;
         }
@@ -620,7 +652,7 @@ function createSocketIOConfig(app, options) {
           if (!auth.isService && auth.userId !== target) {
             rejectTerminal(
               "leave",
-              `user ${auth.userId?.slice(0, 8)}\u2026 tried to leave ${target.slice(0, 8)}\u2026's channel`
+              `user ${auth.userId ? shortId(auth.userId) : "unknown"}\u2026 tried to leave ${shortId(target)}\u2026's channel`
             );
             return;
           }
@@ -721,7 +753,7 @@ function createSocketIOConfig(app, options) {
         if (socket.feathers === context.connection) {
           socket.join(userRoomName(userId));
           console.log(
-            `\u{1F3E0} Socket ${socket.id} joined user room after login: user:${userId.substring(0, 8)}`
+            `\u{1F3E0} Socket ${socket.id} joined user room after login: user:${shortId(userId)}`
           );
           break;
         }

package/dist/daemon/setup/persisted-secret.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Capability-driven secret resolution.
+ *
+ * Shared between JWT secret (`apps/agor-daemon/src/index.ts`) and
+ * `AGOR_MASTER_SECRET` (`apps/agor-daemon/src/startup.ts`). Resolution
+ * order:
+ *
+ *   1. Environment variable present     → use it; no FS touch
+ *   2. Persisted value (already loaded) → use it
+ *   3. config.yaml writable             → generate + persist
+ *   4. None of the above                → fail-fast with concrete remediation
+ *
+ * Failing-fast matters: rotating these secrets on every restart is silently
+ * catastrophic (invalidates every issued token / corrupts every stored
+ * encrypted API key). Refusing to start beats thrashing.
+ *
+ * Admin password bootstrap is deliberately NOT routed through this helper —
+ * it uses a factory-with-rollback inside `bootstrapFirstRunAdmin` so the
+ * shape doesn't match. See `setup/first-run-admin.ts`.
+ *
+ * See context/explorations/daemon-fs-decoupling.md §1.5 (H3) for the
+ * rationale.
+ */
+interface PersistedSecretSpec {
+    /** Human-readable name for error messages (e.g. "JWT secret"). */
+    name: string;
+    /** Environment variable to honor first. */
+    envVar: string;
+    /** Pre-existing value loaded from config, if any. */
+    existing: string | undefined;
+    /** Dotted config key to persist a freshly-generated value at. */
+    configKey: string;
+    /** Generator for new secrets (CSPRNG hex/random — caller's choice). */
+    generate: () => string;
+}
+interface PersistedSecretResult {
+    /** The resolved secret value. */
+    value: string;
+    /** Where the value came from. Callers may use this to shape their logs. */
+    source: 'env' | 'config' | 'generated';
+}
+/**
+ * Resolve a persisted secret per the order above.
+ *
+ * Throws (with operator-actionable remediation) when no source is reachable.
+ * The error always names both the environment-variable escape hatch and the
+ * "make config.yaml writable" escape hatch, so on-call doesn't need to read
+ * the code to recover.
+ */
+declare function resolvePersistedSecret(spec: PersistedSecretSpec): Promise<PersistedSecretResult>;
+
+export { type PersistedSecretResult, type PersistedSecretSpec, resolvePersistedSecret };

package/dist/daemon/setup/persisted-secret.js

@@ -0,0 +1,31 @@
+// src/setup/persisted-secret.ts
+import { setConfigValue } from "@agor/core/config";
+async function resolvePersistedSecret(spec) {
+  const fromEnv = process.env[spec.envVar];
+  if (fromEnv) {
+    return { value: fromEnv, source: "env" };
+  }
+  if (spec.existing) {
+    return { value: spec.existing, source: "config" };
+  }
+  const generated = spec.generate();
+  try {
+    await setConfigValue(spec.configKey, generated);
+  } catch (error) {
+    throw new Error(
+      [
+        `${spec.name} is required and config.yaml is not writable.`,
+        "",
+        `Set the ${spec.envVar} environment variable to a hex-encoded`,
+        "32-byte value (e.g. `openssl rand -hex 32`), or make",
+        "~/.agor/config.yaml writable so the daemon can persist one.",
+        "",
+        `Underlying error: ${error instanceof Error ? error.message : String(error)}`
+      ].join("\n")
+    );
+  }
+  return { value: generated, source: "generated" };
+}
+export {
+  resolvePersistedSecret
+};

package/dist/daemon/setup/socketio.js

@@ -1,4 +1,5 @@
 // src/setup/socketio.ts
+import { shortId } from "@agor/core/db";
 import jwt from "jsonwebtoken";
 function getSocketAuthState(socket) {
   const s = socket;
@@ -102,9 +103,7 @@ function createSocketIOConfig(app, options) {
         }
         const user = await app.service("users").get(decoded.sub);
         socket.feathers = { user };
-        console.log(
-          `\u{1F510} WebSocket authenticated: ${socket.id} (user: ${user.user_id.substring(0, 8)})`
-        );
+        console.log(`\u{1F510} WebSocket authenticated: ${socket.id} (user: ${shortId(user.user_id)})`);
         next();
       } catch (error) {
         console.error(`\u274C WebSocket authentication failed for ${socket.id}:`, error);
@@ -115,7 +114,7 @@ function createSocketIOConfig(app, options) {
       activeConnections++;
       const user = socket.feathers?.user;
       console.log(
-        `\u{1F50C} Socket.io connection established: ${socket.id} (user: ${user ? user.user_id.substring(0, 8) : "unknown"}, total: ${activeConnections})`
+        `\u{1F50C} Socket.io connection established: ${socket.id} (user: ${user ? shortId(user.user_id) : "unknown"}, total: ${activeConnections})`
       );
       if (buildInfo) {
         socket.emit("server-info", {
@@ -126,7 +125,7 @@ function createSocketIOConfig(app, options) {
       if (user?.user_id) {
         socket.join(userRoomName(user.user_id));
         console.log(
-          `\u{1F3E0} Socket ${socket.id} joined user room at connection: user:${user.user_id.substring(0, 8)}`
+          `\u{1F3E0} Socket ${socket.id} joined user room at connection: user:${shortId(user.user_id)}`
         );
       }
       setTimeout(() => {
@@ -178,7 +177,7 @@ function createSocketIOConfig(app, options) {
         if (typeof payloadUserId !== "string" || payloadUserId !== auth.userId) {
           rejectTerminal(
             event,
-            `payload userId (${String(payloadUserId).slice(0, 8)}\u2026) does not match authed userId (${auth.userId.slice(0, 8)}\u2026)`
+            `payload userId (${shortId(String(payloadUserId))}\u2026) does not match authed userId (${shortId(auth.userId)}\u2026)`
           );
           return null;
         }
@@ -202,7 +201,7 @@ function createSocketIOConfig(app, options) {
         if (!auth.isService && auth.userId !== target) {
           rejectTerminal(
             "join",
-            `user ${auth.userId?.slice(0, 8)}\u2026 tried to join ${target.slice(0, 8)}\u2026's channel`
+            `user ${auth.userId ? shortId(auth.userId) : "unknown"}\u2026 tried to join ${shortId(target)}\u2026's channel`
           );
           return;
         }
@@ -220,7 +219,7 @@ function createSocketIOConfig(app, options) {
           if (!auth.isService && auth.userId !== target) {
             rejectTerminal(
               "leave",
-              `user ${auth.userId?.slice(0, 8)}\u2026 tried to leave ${target.slice(0, 8)}\u2026's channel`
+              `user ${auth.userId ? shortId(auth.userId) : "unknown"}\u2026 tried to leave ${shortId(target)}\u2026's channel`
             );
             return;
           }
@@ -321,7 +320,7 @@ function createSocketIOConfig(app, options) {
         if (socket.feathers === context.connection) {
           socket.join(userRoomName(userId));
           console.log(
-            `\u{1F3E0} Socket ${socket.id} joined user room after login: user:${userId.substring(0, 8)}`
+            `\u{1F3E0} Socket ${socket.id} joined user room after login: user:${shortId(userId)}`
           );
           break;
         }

package/dist/daemon/startup.js

@@ -1,8 +1,61 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/setup/persisted-secret.ts
+var persisted_secret_exports = {};
+__export(persisted_secret_exports, {
+  resolvePersistedSecret: () => resolvePersistedSecret
+});
+import { setConfigValue } from "@agor/core/config";
+async function resolvePersistedSecret(spec) {
+  const fromEnv = process.env[spec.envVar];
+  if (fromEnv) {
+    return { value: fromEnv, source: "env" };
+  }
+  if (spec.existing) {
+    return { value: spec.existing, source: "config" };
+  }
+  const generated = spec.generate();
+  try {
+    await setConfigValue(spec.configKey, generated);
+  } catch (error) {
+    throw new Error(
+      [
+        `${spec.name} is required and config.yaml is not writable.`,
+        "",
+        `Set the ${spec.envVar} environment variable to a hex-encoded`,
+        "32-byte value (e.g. `openssl rand -hex 32`), or make",
+        "~/.agor/config.yaml writable so the daemon can persist one.",
+        "",
+        `Underlying error: ${error instanceof Error ? error.message : String(error)}`
+      ].join("\n")
+    );
+  }
+  return { value: generated, source: "generated" };
+}
+var init_persisted_secret = __esm({
+  "src/setup/persisted-secret.ts"() {
+    "use strict";
+  }
+});
+
 // src/startup.ts
+import { promises as fs } from "fs";
+import path from "path";
+import { getAgorHome } from "@agor/core/config";
+import { MessagesRepository, SessionRepository as SessionRepository3, shortId as shortId2 } from "@agor/core/db";
 import { SessionStatus as SessionStatus2, TaskStatus } from "@agor/core/types";
 
 // src/services/health-monitor.ts
 import { ENVIRONMENT } from "@agor/core/config";
+import { shortId } from "@agor/core/db";
 import { NotFoundError } from "@agor/core/utils/errors";
 var HealthMonitor = class {
   app;
@@ -87,14 +140,12 @@ var HealthMonitor = class {
       if (error instanceof NotFoundError) {
         this.stopMonitoring(worktreeId);
         if (process.env.DEBUG) {
-          console.log(
-            `   Health monitoring stopped for deleted worktree ${worktreeId.substring(0, 8)}`
-          );
+          console.log(`   Health monitoring stopped for deleted worktree ${shortId(worktreeId)}`);
         }
         return;
       }
       console.error(
-        `\u274C Health check failed for worktree ${worktreeId.substring(0, 8)}:`,
+        `\u274C Health check failed for worktree ${shortId(worktreeId)}:`,
         error instanceof Error ? error.message : error
       );
     }
@@ -140,7 +191,7 @@ var HealthMonitor = class {
     this.isShuttingDown = true;
     for (const [worktreeId, interval] of this.intervals.entries()) {
       clearInterval(interval);
-      console.log(`   Stopped monitoring: ${worktreeId.substring(0, 8)}`);
+      console.log(`   Stopped monitoring: ${shortId(worktreeId)}`);
     }
     this.intervals.clear();
     console.log("   Health Monitor cleaned up");
@@ -667,11 +718,74 @@ var SchedulerService = class {
   }
 };
 
+// src/utils/append-system-message.ts
+import { generateId, SessionRepository as SessionRepository2 } from "@agor/core/db";
+import { MessageRole } from "@agor/core/types";
+async function appendSystemMessage(opts) {
+  const {
+    app,
+    db,
+    sessionId,
+    taskId,
+    content,
+    contentPreview,
+    type = "system",
+    role = MessageRole.SYSTEM,
+    metadata,
+    params
+  } = opts;
+  const index = await new SessionRepository2(db).countMessages(sessionId);
+  const preview = contentPreview ?? (typeof content === "string" ? content.substring(0, 200) : "");
+  const message = {
+    message_id: generateId(),
+    session_id: sessionId,
+    task_id: taskId,
+    type,
+    role,
+    index,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    content_preview: preview,
+    content,
+    ...metadata ? { metadata } : {}
+  };
+  const created = await app.service("messages").create(message, params ?? {});
+  return created;
+}
+
 // src/startup.ts
+var SENTINEL_FILENAME = "daemon-shutdown-clean.flag";
+var SENTINEL_MAX_AGE_MS = 24 * 60 * 60 * 1e3;
+async function writeCleanShutdownSentinel(signal) {
+  try {
+    const sentinel = { timestamp: (/* @__PURE__ */ new Date()).toISOString(), signal };
+    await fs.writeFile(
+      path.join(getAgorHome(), SENTINEL_FILENAME),
+      JSON.stringify(sentinel),
+      "utf8"
+    );
+  } catch (error) {
+    console.warn(
+      `[startup] Could not write shutdown sentinel \u2014 next restart will be classified as a crash. Cause: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+async function readAndClearSentinel() {
+  const sentinelPath = path.join(getAgorHome(), SENTINEL_FILENAME);
+  try {
+    const raw = await fs.readFile(sentinelPath, "utf8");
+    await fs.unlink(sentinelPath);
+    const sentinel = JSON.parse(raw);
+    const age = Date.now() - new Date(sentinel.timestamp).getTime();
+    return age < SENTINEL_MAX_AGE_MS;
+  } catch {
+    return false;
+  }
+}
 async function cleanupOrphans(ctx) {
-  const { app, sessionsService } = ctx;
+  const { app, db, sessionsService } = ctx;
   const tasksService = app.service("tasks");
   console.log("\u{1F9F9} Cleaning up orphaned tasks and sessions...");
+  const wasGraceful = await readAndClearSentinel();
   const orphanedTasks = await tasksService.getOrphaned();
   if (orphanedTasks.length > 0) {
     console.log(`   Found ${orphanedTasks.length} orphaned task(s)`);
@@ -707,7 +821,7 @@ async function cleanupOrphans(ctx) {
         {}
       );
       console.log(
-        `   \u2713 Marked session ${session.session_id.substring(0, 8)} as idle (was: ${session.status})`
+        `   \u2713 Marked session ${shortId2(session.session_id)} as idle (was: ${session.status})`
       );
     }
   }
@@ -730,7 +844,76 @@ async function cleanupOrphans(ctx) {
           {}
         );
         console.log(
-          `   \u2713 Marked session ${sessionId.substring(0, 8)} as idle (had orphaned tasks, was: ${session.status})`
+          `   \u2713 Marked session ${shortId2(sessionId)} as idle (had orphaned tasks, was: ${session.status})`
+        );
+      }
+    }
+  }
+  const affectedSessionIds = /* @__PURE__ */ new Set([
+    ...orphanedSessions.map((s) => s.session_id),
+    ...Array.from(sessionIdsWithOrphanedTasks)
+  ]);
+  if (affectedSessionIds.size > 0) {
+    const restartType = wasGraceful ? "daemon_restart" : "daemon_crash";
+    const messageText = wasGraceful ? "The Agor daemon was restarted while this session was running. Ask the agent to resume where it left off." : "The Agor daemon restarted unexpectedly while this session was running. Ask the agent to resume where it left off.";
+    const lastOrphanedTaskBySession = /* @__PURE__ */ new Map();
+    for (const task of orphanedTasks) {
+      const sid = task.session_id;
+      const existing = lastOrphanedTaskBySession.get(sid);
+      if (!existing || task.created_at > existing.created_at) {
+        lastOrphanedTaskBySession.set(sid, task);
+      }
+    }
+    const sessionRepo = new SessionRepository3(db);
+    const messageRepo = new MessagesRepository(db);
+    for (const sessionId of affectedSessionIds) {
+      try {
+        let attachTask = lastOrphanedTaskBySession.get(sessionId);
+        if (!attachTask) {
+          const session = await sessionsService.get(sessionId);
+          const latestTaskId = session.tasks?.at(-1);
+          if (latestTaskId) {
+            attachTask = await tasksService.get(latestTaskId);
+          }
+        }
+        if (!attachTask) {
+          console.log(`   \u23ED  Session ${shortId2(sessionId)} has no tasks \u2014 skipping restart notice`);
+          continue;
+        }
+        const messageCount = await sessionRepo.countMessages(sessionId);
+        if (messageCount > 0) {
+          const lastMessages = await messageRepo.findByRange(
+            sessionId,
+            messageCount - 1,
+            messageCount - 1
+          );
+          const last = lastMessages[0];
+          if (last?.type === "daemon_restart" || last?.type === "daemon_crash") {
+            console.log(
+              `   \u23ED  Session ${shortId2(sessionId)} already has a restart notice \u2014 skipping`
+            );
+            continue;
+          }
+        }
+        const injectedMessage = await appendSystemMessage({
+          app,
+          db,
+          sessionId,
+          taskId: attachTask.task_id,
+          type: restartType,
+          content: messageText,
+          metadata: { source: "agor" }
+        });
+        if (attachTask.message_range) {
+          await tasksService.patch(attachTask.task_id, {
+            message_range: { end_index: injectedMessage.index }
+          });
+        }
+        console.log(`   \u2709  Injected ${restartType} notice into session ${shortId2(sessionId)}`);
+      } catch (err) {
+        console.warn(
+          `   \u26A0\uFE0F  Failed to inject restart notice into session ${shortId2(sessionId)}:`,
+          err
         );
       }
     }
@@ -752,22 +935,27 @@ async function cleanupOrphans(ctx) {
   }
 }
 async function ensureMasterSecret(config) {
-  if (!process.env.AGOR_MASTER_SECRET) {
-    const savedSecret = config.daemon?.masterSecret;
-    if (savedSecret) {
-      process.env.AGOR_MASTER_SECRET = savedSecret;
+  const { randomBytes } = await import("crypto");
+  const { resolvePersistedSecret: resolvePersistedSecret2 } = await Promise.resolve().then(() => (init_persisted_secret(), persisted_secret_exports));
+  const resolution = await resolvePersistedSecret2({
+    name: "AGOR_MASTER_SECRET (API key encryption)",
+    envVar: "AGOR_MASTER_SECRET",
+    existing: config.daemon?.masterSecret,
+    configKey: "daemon.masterSecret",
+    generate: () => randomBytes(32).toString("hex")
+  });
+  process.env.AGOR_MASTER_SECRET = resolution.value;
+  switch (resolution.source) {
+    case "env":
+      console.log("\u{1F510} API key encryption enabled (AGOR_MASTER_SECRET set)");
+      break;
+    case "config":
       console.log("\u{1F510} Using saved AGOR_MASTER_SECRET from config");
-    } else {
-      const { randomBytes } = await import("crypto");
-      const { setConfigValue } = await import("@agor/core/config");
-      const generatedSecret = randomBytes(32).toString("hex");
-      await setConfigValue("daemon.masterSecret", generatedSecret);
-      process.env.AGOR_MASTER_SECRET = generatedSecret;
+      break;
+    case "generated":
       console.log("\u{1F510} Generated and saved AGOR_MASTER_SECRET for API key encryption");
       console.log("   Secret stored in ~/.agor/config.yaml");
-    }
-  } else {
-    console.log("\u{1F510} API key encryption enabled (AGOR_MASTER_SECRET set)");
+      break;
   }
 }
 async function startup(ctx) {
@@ -846,6 +1034,7 @@ async function startup(ctx) {
   const shutdown = async (signal) => {
     console.log(`
 \u23F3 Received ${signal}, shutting down gracefully...`);
+    await writeCleanShutdownSentinel(signal);
     try {
       healthMonitor.cleanup();
       if (terminalsService) {

package/dist/daemon/utils/append-system-message.d.ts

@@ -0,0 +1,35 @@
+import { Database } from '@agor/core/db';
+import { Application } from '@agor/core/feathers';
+import { ContentBlock, MessageType, Message, Params } from '@agor/core/types';
+
+/**
+ * appendSystemMessage
+ *
+ * Appends a synthetic message to a session's transcript and broadcasts it via
+ * the FeathersJS messages service (triggering real-time WebSocket events to all
+ * connected clients). Used by startup reconciliation, spawn-failure handling,
+ * env-var validation, and btw result injection.
+ *
+ * Returns the created Message. Callers that need to update a task's
+ * message_range.end_index (e.g. startup.ts) can read it from message.index.
+ */
+
+interface AppendSystemMessageOptions {
+    app: Application;
+    db: Database;
+    sessionId: string;
+    taskId?: string;
+    content: string | ContentBlock[];
+    /** Falls back to the first 200 chars of string content when omitted */
+    contentPreview?: string;
+    /** Defaults to 'system' */
+    type?: Extract<MessageType, 'system' | 'daemon_restart' | 'daemon_crash' | 'widget_request'>;
+    /** Defaults to MessageRole.SYSTEM */
+    role?: Message['role'];
+    metadata?: Message['metadata'];
+    /** FeathersJS request params forwarded to the service create call */
+    params?: Params;
+}
+declare function appendSystemMessage(opts: AppendSystemMessageOptions): Promise<Message>;
+
+export { type AppendSystemMessageOptions, appendSystemMessage };

package/dist/daemon/utils/append-system-message.js

@@ -0,0 +1,36 @@
+// src/utils/append-system-message.ts
+import { generateId, SessionRepository } from "@agor/core/db";
+import { MessageRole } from "@agor/core/types";
+async function appendSystemMessage(opts) {
+  const {
+    app,
+    db,
+    sessionId,
+    taskId,
+    content,
+    contentPreview,
+    type = "system",
+    role = MessageRole.SYSTEM,
+    metadata,
+    params
+  } = opts;
+  const index = await new SessionRepository(db).countMessages(sessionId);
+  const preview = contentPreview ?? (typeof content === "string" ? content.substring(0, 200) : "");
+  const message = {
+    message_id: generateId(),
+    session_id: sessionId,
+    task_id: taskId,
+    type,
+    role,
+    index,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    content_preview: preview,
+    content,
+    ...metadata ? { metadata } : {}
+  };
+  const created = await app.service("messages").create(message, params ?? {});
+  return created;
+}
+export {
+  appendSystemMessage
+};