@schlessera/brain-ui-server 0.32.0 → 0.33.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@schlessera/brain-ui-server",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "description": "brain-kit chat-UI server: Hono app factory, WebSocket turn coordinator, auth (password/passkeys/tailscale/proxy), session catalog, and brain/files/voice routes",
   "license": "MIT",
   "keywords": [
@@ -27,6 +27,9 @@
   },
   "sideEffects": false,
   "type": "module",
+  "bin": {
+    "brain-ui-cron": "./dist/bin/brain-ui-cron.js"
+  },
   "exports": {
     ".": {
       "bun": "./src/index.ts",
@@ -51,8 +54,8 @@
   "dependencies": {
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/api-logs": "0.221.0",
-    "@schlessera/brain-render-template": "0.32.0",
-    "@schlessera/brain-ui-sdk": "0.32.0",
+    "@schlessera/brain-render-template": "0.33.0",
+    "@schlessera/brain-ui-sdk": "0.33.0",
     "@simplewebauthn/server": "^13.3.2",
     "fflate": "^0.8.2",
     "gray-matter": "^4.0.3",

package/src/app.ts

@@ -53,7 +53,7 @@ import {
   createBackendRegistry,
   type BackendRegistry,
 } from "./agent/backend.js";
-import { createBrainClient } from "./brain/client.js";
+import { createBrainClient, probeBrainCliVersion } from "./brain/client.js";
 import { createCronScheduler } from "./cron/scheduler.js";
 import { WsHost } from "./ws/host.js";
 import { createWsUpgrade, websocket } from "./ws/connection.js";
@@ -177,6 +177,7 @@ export function createApp(options: CreateAppOptions = {}): BrainUiApp {
   // Per-instance state: the app's own database, the brain CLI wrapper, the
   // backend registry, and the WebSocket host. No module-level singletons —
   // two apps with different configuration coexist in one process.
+  probeBrainCliVersion(config.brainPath, observability.logger("brain"));
   const dbLog = observability.logger("db");
   const db = createUiDb(config.dbPath, { log: dbLog });
   const brain = createBrainClient({ brainPath: config.brainPath });

package/src/bin/brain-ui-cron.ts

@@ -0,0 +1,152 @@
+#!/usr/bin/env bun
+/** Thin argv dispatcher for the ui-server's container cron jobs. */
+
+import { statSync } from "fs";
+import { join } from "path";
+
+import { resolveCronConfig } from "../config/env.js";
+import { runDigest } from "../cron/digest.js";
+import {
+  emitCrontab,
+  emitEnvironment,
+  type BrainModuleListPayload,
+} from "../cron/emit.js";
+import { runJob } from "../cron/run-job.js";
+
+/**
+ * The bash this replaced tested `[ -f … ]`, which is true only for a regular
+ * file (following symlinks). `existsSync` would also accept a directory, and a
+ * directory at that path would put a root cron line in the crontab that the
+ * shell has always skipped.
+ */
+function isRegularFile(path: string): boolean {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+
+export const USAGE = `usage: brain-ui-cron run <job-name> -- <command...>
+       brain-ui-cron digest
+       brain-ui-cron crontab [--wrapper-command <command>] [--digest-command <command>] [--path-line <line>] [--user <user>]
+       brain-ui-cron environment`;
+
+const DEFAULT_WRAPPER_COMMAND = "bun /opt/brain-ui/server/scripts/cron-run.ts";
+const DEFAULT_DIGEST_COMMAND = "bun /opt/brain-ui/server/scripts/brain-digest.ts";
+const DEFAULT_PATH_LINE =
+  "PATH=/root/.local/bin:/root/.bun/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin";
+const DEFAULT_USER = "root";
+
+function usage(): never {
+  process.stderr.write(`${USAGE}\n`);
+  process.exit(2);
+}
+
+function crontabOptions(args: string[]): {
+  wrapperCommand: string;
+  digestCommand: string;
+  pathLine: string;
+  user: string;
+} {
+  const values = new Map<string, string>();
+  const accepted = new Set([
+    "--wrapper-command",
+    "--digest-command",
+    "--path-line",
+    "--user",
+  ]);
+  for (let i = 0; i < args.length; i += 2) {
+    const flag = args[i];
+    const value = args[i + 1];
+    if (!accepted.has(flag) || value === undefined || value === "" || value.startsWith("--")) {
+      usage();
+    }
+    values.set(flag, value);
+  }
+  return {
+    wrapperCommand: values.get("--wrapper-command") ?? DEFAULT_WRAPPER_COMMAND,
+    digestCommand: values.get("--digest-command") ?? DEFAULT_DIGEST_COMMAND,
+    pathLine: values.get("--path-line") ?? DEFAULT_PATH_LINE,
+    user: values.get("--user") ?? DEFAULT_USER,
+  };
+}
+
+async function readModuleList(
+  brainPath: string,
+  env: Record<string, string | undefined>
+): Promise<BrainModuleListPayload | null> {
+  try {
+    const proc = Bun.spawn(["brain", "module", "list", "--json"], {
+      cwd: brainPath,
+      env,
+      stdout: "pipe",
+      stderr: "ignore",
+    });
+    const [exitCode, stdout] = await Promise.all([
+      proc.exited,
+      new Response(proc.stdout).text(),
+    ]);
+    if (exitCode !== 0 || stdout.trim() === "") return null;
+    const parsed: unknown = JSON.parse(stdout);
+    if (
+      !parsed ||
+      typeof parsed !== "object" ||
+      !Array.isArray((parsed as Partial<BrainModuleListPayload>).enabled) ||
+      !Array.isArray((parsed as Partial<BrainModuleListPayload>).available)
+    ) {
+      return null;
+    }
+    return parsed as BrainModuleListPayload;
+  } catch {
+    return null;
+  }
+}
+
+const [subcommand, ...args] = process.argv.slice(2);
+const config = resolveCronConfig();
+
+if (subcommand === "run") {
+  const [jobName, separator, ...command] = args;
+  if (!jobName || separator !== "--" || command.length === 0) usage();
+  process.exit(
+    await runJob({
+      jobName,
+      command,
+      dbPath: config.dbPath,
+      childEnv: config.childEnv,
+    })
+  );
+}
+
+if (subcommand === "digest" && args.length === 0) {
+  process.exit(runDigest({ dbPath: config.dbPath }));
+}
+
+if (subcommand === "crontab") {
+  const options = crontabOptions(args);
+  const modules = await readModuleList(config.brainPath, config.childEnv);
+  process.stdout.write(
+    emitCrontab({
+      ...options,
+      modules,
+      legacyScraperPresent: isRegularFile(
+        join(config.brainPath, "scripts", "jobs", "scrape-all.ts")
+      ),
+    })
+  );
+  process.exit(0);
+}
+
+if (subcommand === "environment" && args.length === 0) {
+  try {
+    process.stdout.write(emitEnvironment(config.childEnv));
+    process.exit(0);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`[brain-ui-cron] ${message}\n`);
+    process.exit(1);
+  }
+}
+
+usage();

package/src/brain/client.ts

@@ -1,5 +1,6 @@
 import { existsSync } from "fs";
 import { join } from "path";
+import type { Logger } from "@opentelemetry/api-logs";
 import { subprocessEnv } from "../config/env.js";
 import type {
   BrainSearchResult,
@@ -48,6 +49,13 @@ interface ExecResult {
   exitCode: number;
 }
 
+/**
+ * First core release whose parser understands `--`. The ui-server inserts the
+ * separator before user input, so an older brain repo pin would lose every
+ * positional silently.
+ */
+export const MIN_BRAIN_CLI_VERSION = "0.33.0";
+
 /**
  * argv prefix for invoking the brain CLI inside `brainPath`.
  *
@@ -67,6 +75,88 @@ export function brainCliCommand(brainPath: string): string[] {
   return ["bun", "scripts/brain-cli.ts"];
 }
 
+interface ParsedVersion {
+  major: number;
+  minor: number;
+  patch: number;
+  prerelease: boolean;
+}
+
+function parseVersion(value: string): ParsedVersion | null {
+  const match = value.match(
+    // Full SemVer 2.0.0 grammar: prerelease and build metadata are
+    // dot-separated NON-EMPTY identifiers. A loose `[0-9A-Za-z.-]+` would
+    // accept "0.32.9-.." and treat garbage as a real prerelease, which the
+    // comparison below would then refuse to boot on instead of warning.
+    /^v?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/
+  );
+  if (!match) return null;
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    prerelease: match[4] !== undefined,
+  };
+}
+
+function isBelowMinimum(found: ParsedVersion, minimum: ParsedVersion): boolean {
+  for (const key of ["major", "minor", "patch"] as const) {
+    if (found[key] !== minimum[key]) return found[key] < minimum[key];
+  }
+  return found.prerelease && !minimum.prerelease;
+}
+
+/** Probe the brain repo's own CLI pin, refusing only known-incompatible versions. */
+export function probeBrainCliVersion(brainPath: string, log: Logger): void {
+  let result: ReturnType<typeof Bun.spawnSync>;
+  try {
+    result = Bun.spawnSync([...brainCliCommand(brainPath), "--version"], {
+      cwd: brainPath,
+      stdout: "pipe",
+      stderr: "pipe",
+      env: subprocessEnv({ NO_COLOR: "1" }),
+      timeout: 5_000,
+    });
+  } catch (error) {
+    log.emit({
+      severityText: "WARN",
+      body: "brain CLI version probe failed; continuing",
+      attributes: {
+        reason: error instanceof Error ? error.message : String(error),
+      },
+    });
+    return;
+  }
+
+  if (result.exitCode !== 0) {
+    log.emit({
+      severityText: "WARN",
+      body: "brain CLI version probe failed; continuing",
+      attributes: { "exit.code": result.exitCode },
+    });
+    return;
+  }
+
+  const foundText = new TextDecoder().decode(result.stdout).trim();
+  const found = parseVersion(foundText);
+  const minimum = parseVersion(MIN_BRAIN_CLI_VERSION)!;
+  if (!found) {
+    log.emit({
+      severityText: "WARN",
+      body: "brain CLI returned an unparseable version; continuing",
+      attributes: { version: foundText },
+    });
+    return;
+  }
+
+  if (isBelowMinimum(found, minimum)) {
+    throw new Error(
+      `brain CLI version ${foundText} is incompatible: version ${MIN_BRAIN_CLI_VERSION} ` +
+        `or newer is required; bump the brain repo's @schlessera/brain pin before deploying.`
+    );
+  }
+}
+
 export function createBrainClient(opts: { brainPath: string }): BrainClient {
   const { brainPath } = opts;
 
@@ -108,11 +198,12 @@ export function createBrainClient(opts: { brainPath: string }): BrainClient {
     },
 
     async search(query, opts) {
-      const args = ["search", query];
+      const args = ["search"];
       if (opts?.type) args.push("--type", opts.type);
       if (opts?.tag) args.push("--tag", opts.tag);
       if (opts?.limit) args.push("--limit", String(opts.limit));
       if (opts?.mode) args.push("--mode", opts.mode);
+      args.push("--", query);
 
       const result = await execBrain(args);
       const parsed = parseJsonOutput<BrainSearchResponse | BrainSearchResult[]>(result);
@@ -146,7 +237,7 @@ export function createBrainClient(opts: { brainPath: string }): BrainClient {
     },
 
     async read(path) {
-      const result = await execBrain(["read", path]);
+      const result = await execBrain(["read", "--", path]);
       if (result.exitCode !== 0) {
         throw new Error(`brain read failed: ${result.stderr}`);
       }
@@ -178,10 +269,11 @@ export function createBrainClient(opts: { brainPath: string }): BrainClient {
     },
 
     async add(content, opts) {
-      const args = ["add", content];
+      const args = ["add"];
       if (opts?.type) args.push("--type", opts.type);
       if (opts?.title) args.push("--title", opts.title);
       if (opts?.tags) args.push("--tags", opts.tags.join(","));
+      args.push("--", content);
 
       const result = await execBrain(args);
       if (result.exitCode !== 0) {

package/src/config/env.ts

@@ -105,8 +105,11 @@ export const ENV_VARS: readonly EnvVarDescriptor[] = [
   },
   {
     name: "DB_PATH",
-    description: "SQLite file for the UI's own database (sessions, passkeys, settings).",
-    default: "./brain-ui.db",
+    description:
+      "SQLite file for the UI's own database (sessions, passkeys, settings). " +
+      "The server factory defaults to ./brain-ui.db; brain-ui-cron defaults " +
+      "to the container path /data/db/brain-ui.db.",
+    default: "./brain-ui.db (server); /data/db/brain-ui.db (brain-ui-cron)",
     required: false,
   },
   {
@@ -494,6 +497,16 @@ export interface ServerConfig {
 
 type EnvRecord = Record<string, string | undefined>;
 
+/** Configuration resolved specifically for the standalone cron bin. */
+export interface CronConfig {
+  /** Brain repository inspected by the crontab emitter. */
+  brainPath: string;
+  /** The deployment database; unlike createApp(), the bin defaults to the container path. */
+  dbPath: string;
+  /** Exact inherited environment for the scheduled child, before the span sink is added. */
+  childEnv: EnvRecord;
+}
+
 function list(raw: string | undefined): string[] {
   return (raw ?? "")
     .split(",")
@@ -662,6 +675,20 @@ export function resolveServerConfig(env: EnvRecord = process.env): ServerConfig
   };
 }
 
+/**
+ * Resolve the standalone cron bin's environment without applying the server's
+ * subprocess secret filter. Scheduled jobs inherit the same environment they
+ * did before this behavior moved out of the deployment shell; narrowing that
+ * environment belongs to the later least-privilege release.
+ */
+export function resolveCronConfig(env: EnvRecord = process.env): CronConfig {
+  return {
+    brainPath: env.BRAIN_PATH || "/data/brain",
+    dbPath: env.DB_PATH || "/data/db/brain-ui.db",
+    childEnv: { ...env },
+  };
+}
+
 /**
  * The filtered parent environment for spawned subprocesses (brain CLI,
  * whatsup), plus explicit overrides. The shared descriptor strips server-only

package/src/cron/digest.ts

@@ -0,0 +1,45 @@
+/** The standalone daily activity-digest job. Failures are deliberately loud. */
+import { generateActivityDigest } from "../activity/digest.js";
+import { createUiDb } from "../db/client.js";
+
+interface TextSink {
+  write(text: string): unknown;
+}
+
+export interface DigestOptions {
+  dbPath: string;
+  stdout?: TextSink;
+  stderr?: TextSink;
+}
+
+export interface DigestDependencies {
+  createDb?: typeof createUiDb;
+  generateDigest?: typeof generateActivityDigest;
+}
+
+/** Generate and persist one digest, returning a process-compatible status. */
+export function runDigest(
+  options: DigestOptions,
+  dependencies: DigestDependencies = {}
+): number {
+  const stdout = options.stdout ?? process.stdout;
+  const stderr = options.stderr ?? process.stderr;
+  const openDb = dependencies.createDb ?? createUiDb;
+  const generate = dependencies.generateDigest ?? generateActivityDigest;
+  let db: ReturnType<typeof createUiDb> | undefined;
+
+  try {
+    db = openDb(options.dbPath);
+    const digest = generate(db);
+    stdout.write(
+      `[brain-digest] generated: ${digest.runs} runs, ${digest.failures} failures, $${digest.costUsd.toFixed(2)}\n`
+    );
+    return 0;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    stderr.write(`[brain-digest] failed: ${message}\n`);
+    return 1;
+  } finally {
+    db?.close();
+  }
+}

package/src/cron/emit.ts

@@ -0,0 +1,230 @@
+import {
+  SUBPROCESS_ENV,
+  type SubprocessEnvAudience,
+} from "@schlessera/brain-ui-sdk/server";
+
+/** One cron manifest entry in `brain module list --json`. */
+export interface BrainModuleListCronEntry {
+  name: string;
+  schedule: string;
+  command: string;
+}
+
+/** One enabled module in the core CLI's module-list payload. */
+export interface BrainModuleListEnabledModule {
+  name: string;
+  key: string;
+  description: string | null;
+  types: string[];
+  commands: string[];
+  cron: BrainModuleListCronEntry[];
+}
+
+/** One disabled-but-available module in the core CLI's module-list payload. */
+export interface BrainModuleListAvailableModule {
+  key: string;
+  description: string | null;
+  enabled: false;
+}
+
+/** The payload emitted by `brain module list --json`. */
+export interface BrainModuleListPayload {
+  enabled: BrainModuleListEnabledModule[];
+  available: BrainModuleListAvailableModule[];
+}
+
+export interface EmitCrontabOptions {
+  /** Null means the core CLI was unavailable or did not return JSON. */
+  modules: BrainModuleListPayload | null;
+  /** Command prefix that records and runs one job. */
+  wrapperCommand: string;
+  /** Command executed inside the wrapper's `digest` job. */
+  digestCommand: string;
+  /** Complete `PATH=...` crontab line. */
+  pathLine: string;
+  /** System crontab user field. */
+  user: string;
+  /** Whether `scripts/jobs/scrape-all.ts` exists in the brain repository. */
+  legacyScraperPresent: boolean;
+}
+
+const MODULE_NAME = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const CRON_NAME = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const CRON_SCHEDULE = /^[-0-9*,/ ]{1,100}$/;
+const CRON_COMMAND = /^[A-Za-z0-9 _.:=@,/-]{1,200}$/;
+
+// These use ^...$ without the `m` flag deliberately. In JavaScript `$`
+// matches only at the true end of the string, so these are the correct
+// translation of the bash jq/Oniguruma guards, which needed \A...\z because
+// Oniguruma's `$` can match before a trailing newline.
+function validModuleName(value: unknown): value is string {
+  return typeof value === "string" && MODULE_NAME.test(value);
+}
+
+function validCronEntry(value: unknown): value is BrainModuleListCronEntry {
+  if (!value || typeof value !== "object") return false;
+  const entry = value as Partial<BrainModuleListCronEntry>;
+  return (
+    typeof entry.name === "string" &&
+    CRON_NAME.test(entry.name) &&
+    typeof entry.schedule === "string" &&
+    CRON_SCHEDULE.test(entry.schedule) &&
+    typeof entry.command === "string" &&
+    CRON_COMMAND.test(entry.command)
+  );
+}
+
+function assertSingleLine(name: string, value: string): void {
+  if (/[\0\r\n]/.test(value)) {
+    throw new Error(`${name} must be a single line`);
+  }
+}
+
+/**
+ * Emit `/etc/cron.d/brain-ui` with the same byte layout as the deployment
+ * shell's historical `generate_crontab` function.
+ */
+export function emitCrontab(options: EmitCrontabOptions): string {
+  const {
+    modules,
+    wrapperCommand,
+    digestCommand,
+    pathLine,
+    user,
+    legacyScraperPresent,
+  } = options;
+
+  assertSingleLine("wrapperCommand", wrapperCommand);
+  assertSingleLine("digestCommand", digestCommand);
+  assertSingleLine("pathLine", pathLine);
+  assertSingleLine("user", user);
+
+  const lines = [
+    "# Generated by entrypoint.sh — regenerated on each container start.",
+    pathLine,
+    "",
+    "# Base jobs",
+    `0 2 * * * ${user} cd /data/brain && ${wrapperCommand} sync -- sh -c 'brain sync && brain index' 2>&1 | logger -t brain-sync`,
+    `0 3 * * * ${user} cd /data/brain && ${wrapperCommand} validate -- brain validate 2>&1 | logger -t brain-validate`,
+    `0 7 * * * ${user} cd /data/brain && ${wrapperCommand} maintain -- brain maintain 2>&1 | logger -t brain-maintain`,
+    `30 7 * * * ${user} cd /data/brain && ${wrapperCommand} digest -- ${digestCommand} 2>&1 | logger -t brain-digest`,
+    "",
+    "# Module jobs (from enabled modules' cron manifests, when exposed)",
+  ];
+
+  const enabled = modules && Array.isArray(modules.enabled) ? modules.enabled : [];
+  if (modules === null) {
+    lines.push("# (brain module list unavailable — module cron skipped)");
+  } else {
+    for (const module of enabled) {
+      if (!module || typeof module !== "object" || !validModuleName(module.name)) continue;
+      const entries = Array.isArray(module.cron) ? module.cron : [];
+      for (const entry of entries) {
+        if (!validCronEntry(entry)) continue;
+        const jobName = `${module.name}-${entry.name}`;
+        lines.push(
+          `${entry.schedule} ${user} cd /data/brain && ${wrapperCommand} ${jobName} -- brain ${entry.command} 2>&1 | logger -t brain-${jobName}`
+        );
+      }
+    }
+  }
+
+  const jobsModuleEnabled = enabled.some(
+    (module) =>
+      module &&
+      typeof module === "object" &&
+      Array.isArray(module.commands) &&
+      module.commands.includes("jobs")
+  );
+  // Keep the historical standalone scraper fallback for brain repositories
+  // that have not moved their jobs workflow to an enabled module.
+  if (!jobsModuleEnabled && legacyScraperPresent) {
+    lines.push(
+      `0 4 * * * ${user} cd /data/brain && ${wrapperCommand} jobs -- bun scripts/jobs/scrape-all.ts --api-only 2>&1 | logger -t brain-jobs`
+    );
+  }
+
+  lines.push("");
+  return `${lines.join("\n")}\n`;
+}
+
+/**
+ * NODE_ENV is in the descriptor because Bun uses it to choose `.env.<mode>` in
+ * every child spawned by the server. Scheduled jobs take a different path:
+ * they historically receive their environment through pam_env without
+ * NODE_ENV, and adding it would change which brain-repo env file their Bun
+ * commands load. Revisit this explicit subtraction in the 0.33.1
+ * subprocess-environment allowlist unit.
+ */
+export const CRON_ENV_EXCLUSIONS: ReadonlySet<string> = new Set(["NODE_ENV"]);
+
+/**
+ * The order the shell emitted `/etc/environment` in. pam_env does not care,
+ * but the historical golden is byte-exact and this is what it is compared
+ * against.
+ *
+ * Order lives HERE, not in the SDK descriptor: the SET is owned by
+ * `SUBPROCESS_ENV`'s cron audience (see {@link CRON_ENV_NAMES}, which fails
+ * loudly if the two ever disagree), and making an unrelated file's declaration
+ * order load-bearing for a cosmetic property would be a trap for whoever next
+ * tidies it.
+ */
+const CRON_ENV_ORDER: readonly string[] = [
+  "PATH",
+  "BRAIN_PATH",
+  "TZ",
+  "DB_PATH",
+  "GEMINI_API_KEY",
+  "OPENAI_API_KEY",
+  "GITHUB_TOKEN",
+  "BRAIN_UI_SYNC_GITHUB_TOKEN",
+  "CLAUDE_CODE_OAUTH_TOKEN",
+  "BRAIN_UI_PRICING_DISCOVERY",
+  "BRAIN_UI_PRICING_TTL_HOURS",
+];
+
+/**
+ * Names emitted into `/etc/environment`: the SDK's cron audience minus the
+ * explicit exclusions, in {@link CRON_ENV_ORDER}.
+ *
+ * A variable that joins or leaves the cron audience and is not accounted for
+ * here throws at module load rather than silently changing what scheduled jobs
+ * can see.
+ */
+export const CRON_ENV_NAMES = Object.freeze(
+  (() => {
+    const audience = Object.entries(SUBPROCESS_ENV)
+      .filter(([, audiences]) =>
+        (audiences as readonly SubprocessEnvAudience[]).includes("cron")
+      )
+      .map(([name]) => name)
+      .filter((name) => !CRON_ENV_EXCLUSIONS.has(name));
+    const ordered = new Set(CRON_ENV_ORDER);
+    const missing = audience.filter((name) => !ordered.has(name));
+    const extra = CRON_ENV_ORDER.filter((name) => !audience.includes(name));
+    if (missing.length > 0 || extra.length > 0) {
+      throw new Error(
+        "cron environment list drifted from SUBPROCESS_ENV's cron audience: " +
+          `unordered=[${missing.join(", ")}] unknown=[${extra.join(", ")}]`
+      );
+    }
+    return CRON_ENV_ORDER.slice();
+  })()
+);
+
+/** Emit the pam_env input consumed by scheduled jobs. */
+export function emitEnvironment(env: Record<string, string | undefined>): string {
+  const lines: string[] = [];
+  for (const name of CRON_ENV_NAMES) {
+    const value = env[name];
+    // Match the shell's `[ -n ]`: both unset and empty values are omitted.
+    if (!value) continue;
+    // /etc/environment has no shell-safe interpolation layer. Reject anything
+    // that could terminate/escape the quoted value or create another line.
+    if (/[\0"\\\r\n]/.test(value)) {
+      throw new Error(`cannot emit unsafe /etc/environment value for ${name}`);
+    }
+    lines.push(`${name}="${value}"`);
+  }
+  return lines.length === 0 ? "" : `${lines.join("\n")}\n`;
+}