@volter/supercode-orchestrator 0.4.4

package/cron.mjs

@@ -0,0 +1,967 @@
+// The cron half of the tick (docs/ORCHESTRATOR-IR.md §4.3).
+//
+//   cronTick(state, ev, effects)   due jobs -> claim -> run; obligation retry; breakers
+//   fireFinal / fireFailed          the worker events of a fire's own session
+//   nextRunAt(schedule, after, zone) once | interval | cron; a cron without a tz on the home's clock (homeZone)
+//
+// Pure, like the reducer it hooks into: no node module, no wall clock, no I/O.
+// Time arrives as the event's `at`; delivery leaves as effects. The cron
+// evaluator is ours (five fields, Vixie day-of-month/day-of-week semantics);
+// zone arithmetic goes through `Intl`, which is a language builtin, not a
+// module.
+
+import { surfaceKeyString } from './ir.mjs';
+import { homeChannel } from './ir.mjs';
+import { endBinding, ensureRuntime, leaseId, newObligation, permissionResponse, reply } from './reducer.mjs';
+
+/** Retry delays after the 1st, 2nd and 3rd send attempt (§4.3 "retry pending obligations"). */
+export const BACKOFF_MINUTES = Object.freeze([1, 2, 4]);
+/** Consecutive send failures on one adapter that open its breaker, and for how long (§2.8). */
+export const BREAKER_FAILURES = 3;
+export const BREAKER_MINUTES = 5;
+export const MAX_ATTEMPTS = 3;
+
+/**
+ * Hermes `_summarize_cron_failure_for_delivery`, transcribed: the one line a
+ * chat gets for a failed run (the full error stays in the run's output file).
+ * A no_agent job never reached a provider, so the provider branches are
+ * skipped for it. The fallback clause is Hermes's no-chain wording, the
+ * orchestrator having no fallback chain.
+ */
+export function summarizeFailure(job, error) {
+  const name = job?.residue?.name || job?.id || 'cron job';
+  const text = String(error || 'unknown error').trim();
+  const lower = text.toLowerCase();
+  const provider = !(job?.residue?.no_agent === true);
+  const fallback = 'No fallback chain configured — add one with `hermes fallback add`, or set a cron fleet default via `cron.model` + `cron.model_provider` in config.yaml.';
+  if (lower.startsWith('script timed out')) return `⚠️ Cron '${name}' failed: script timed out. No model was invoked. Full details saved in cron output.`;
+  if (provider && (/\b429\b/.test(text) || lower.includes('rate limit') || lower.includes('usage limit'))) {
+    const reason = lower.includes('weekly usage limit') ? 'weekly usage limit' : lower.includes('quota') ? 'quota limit' : 'rate limit';
+    return `⚠️ Cron '${name}' failed: provider ${reason}. ${fallback} Full details saved in cron output.`;
+  }
+  if (/idle for \d+s\s*\(limit \d+s\)/.test(lower) || lower.startsWith('no activity from the worker')) {
+    return `⚠️ Cron '${name}' failed: the job itself stalled — no tool/API activity for the configured inactivity window. Not a provider or fallback-chain issue; check what the job was doing when it went quiet. Full details saved in cron output.`;
+  }
+  if (provider && (lower.includes('readtimeout') || lower.includes('timed out') || lower.includes('timeout'))) return `⚠️ Cron '${name}' failed: provider timeout. ${fallback} Full details saved in cron output.`;
+  if (provider && (/authenticat|authoriz/.test(lower) || /\b(401|403)\b/.test(text))) return `⚠️ Cron '${name}' failed: provider authentication error. Full details saved in cron output.`;
+  let cleaned = text.slice(0, 2000).replace(/^(RuntimeError|Exception|ValueError|HTTPStatusError):\s*/, '').replace(/\s+/g, ' ').trim();
+  if (cleaned.length > 180) cleaned = `${cleaned.slice(0, 177).trimEnd()}...`;
+  return `⚠️ Cron '${name}' failed: ${cleaned}`;
+}
+
+/**
+ * Hermes `is_autonomous_silence_response` (`gateway/response_filters.py`):
+ * a cron or webhook answer that is a silence marker (`[SILENT]`, `SILENT`,
+ * `NO_REPLY`, `NO REPLY`) as a whole, on its own first or last line, or the
+ * bracketed sentinel opening the response, is not delivered.
+ */
+const SILENCE_MARKERS = new Set(['[SILENT]', 'SILENT', 'NO_REPLY', 'NO REPLY']);
+export function isSilence(response) {
+  if (typeof response !== 'string') return false;
+  const stripped = response.trim();
+  if (!stripped) return false;
+  const token = (line) => SILENCE_MARKERS.has(line.trim().toUpperCase().split(/\s+/).join(' '));
+  if (token(stripped)) return true;
+  const lines = stripped.split(/\r\n|[\n\r\v\f\x1c\x1d\x1e\x85\u2028\u2029]/).filter((l) => l.trim());
+  if (lines.length && (token(lines[0]) || token(lines[lines.length - 1]))) return true;
+  return stripped.toUpperCase().startsWith('[SILENT]');
+}
+
+// ---------------------------------------------------------------- cron expressions
+
+const MONTHS = { jan: 1, feb: 2, mar: 3, apr: 4, may: 5, jun: 6, jul: 7, aug: 8, sep: 9, oct: 10, nov: 11, dec: 12 };
+const DAYS = { sun: 0, mon: 1, tue: 2, wed: 3, thu: 4, fri: 5, sat: 6 };
+
+function fieldNumber(text, kind) {
+  const t = text.trim().toLowerCase();
+  if (kind === 'month' && MONTHS[t.slice(0, 3)] !== undefined && !/^\d+$/.test(t)) return MONTHS[t.slice(0, 3)];
+  if (kind === 'dow' && DAYS[t.slice(0, 3)] !== undefined && !/^\d+$/.test(t)) return DAYS[t.slice(0, 3)];
+  if (!/^\d+$/.test(t)) throw new TypeError(`cron: ${JSON.stringify(text)} is not a ${kind} value`);
+  return Number(t);
+}
+
+// One cron field -> the set of values it matches.
+// Supports a star, `a`, `a-b`, star-slash-n, `a-b/n`, and comma lists.
+function cronField(spec, kind, lo, hi) {
+  const out = new Set();
+  for (const item of String(spec).split(',')) {
+    const slash = item.indexOf('/');
+    const rangePart = slash < 0 ? item : item.slice(0, slash);
+    const step = slash < 0 ? 1 : Number(item.slice(slash + 1));
+    if (!Number.isInteger(step) || step < 1) throw new TypeError(`cron: bad step in ${JSON.stringify(item)}`);
+    let a; let b;
+    if (rangePart === '*') { a = lo; b = hi; }
+    else {
+      const dash = rangePart.indexOf('-', 1);
+      if (dash > 0) { a = fieldNumber(rangePart.slice(0, dash), kind); b = fieldNumber(rangePart.slice(dash + 1), kind); }
+      else { a = fieldNumber(rangePart, kind); b = slash < 0 ? a : hi; }
+    }
+    if (a < lo || b > hi || a > b) throw new TypeError(`cron: ${JSON.stringify(item)} out of range for ${kind}`);
+    for (let v = a; v <= b; v += step) out.add(kind === 'dow' ? v % 7 : v);
+  }
+  if (!out.size) throw new TypeError(`cron: ${JSON.stringify(spec)} matches nothing`);
+  return out;
+}
+
+/** `min hour dom month dow` -> matcher. */
+export function parseCron(expr) {
+  const parts = String(expr ?? '').trim().split(/\s+/).filter(Boolean);
+  if (parts.length !== 5) throw new TypeError(`cron: expected five fields, got ${parts.length} in ${JSON.stringify(expr)}`);
+  return {
+    minute: cronField(parts[0], 'minute', 0, 59),
+    hour: cronField(parts[1], 'hour', 0, 23),
+    dom: cronField(parts[2], 'dom', 1, 31),
+    month: cronField(parts[3], 'month', 1, 12),
+    dow: cronField(parts[4], 'dow', 0, 7),
+    domRestricted: parts[2] !== '*',
+    dowRestricted: parts[4] !== '*',
+  };
+}
+
+// ---------------------------------------------------------------- zones
+
+const FORMATTERS = new Map();
+function zoneParts(tz, utcMs) {
+  let f = FORMATTERS.get(tz);
+  if (!f) {
+    f = new Intl.DateTimeFormat('en-US', { timeZone: tz, hourCycle: 'h23', year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit', second: '2-digit' });
+    FORMATTERS.set(tz, f);
+  }
+  const p = {};
+  for (const part of f.formatToParts(new Date(utcMs))) if (part.type !== 'literal') p[part.type] = Number(part.value);
+  return p;
+}
+
+/**
+ * The clock a cron job without a zone runs on, as Hermes's (`hermes_time.get_timezone`): the home's
+ * `timezone`, else the host's zone; a name the host does not know is the host's zone, as Hermes falls back.
+ */
+export function homeZone(profile) {
+  const host = Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC';
+  const named = typeof profile?.residue?.config?.timezone === 'string' ? profile.residue.config.timezone.trim() : '';
+  if (!named) return host;
+  try { zoneParts(named, 0); return named; } catch { return host; }
+}
+
+/**
+ * Refuse a zone `Intl` does not know, by name. Unchecked, `Intl`'s own
+ * RangeError would surface from `nextRunAt` only after a fire had run.
+ */
+function checkZone(tz) {
+  if (!tz || tz === 'UTC') return;
+  try { zoneParts(tz, 0); } catch {
+    throw new RangeError(`schedule.tz ${JSON.stringify(tz)} is not an IANA time zone (such as America/New_York)`);
+  }
+}
+
+/** `wall clock in tz` - `UTC`, in ms, at that instant. */
+function zoneOffsetMs(tz, utcMs) {
+  if (!tz || tz === 'UTC') return 0;
+  const p = zoneParts(tz, utcMs);
+  return Date.UTC(p.year, p.month - 1, p.day, p.hour % 24, p.minute, p.second) - Math.floor(utcMs / 1000) * 1000;
+}
+
+/** A wall-clock instant in `tz` (expressed as a UTC-shifted ms value) back to real UTC ms. */
+function localToUtc(tz, localMs) {
+  if (!tz || tz === 'UTC') return localMs;
+  let guess = localMs - zoneOffsetMs(tz, localMs);
+  for (let i = 0; i < 2; i++) {
+    const next = localMs - zoneOffsetMs(tz, guess);
+    if (next === guess) break;
+    guess = next;
+  }
+  return guess;
+}
+
+function matchesDay(f, d) {
+  if (!f.month.has(d.getUTCMonth() + 1)) return false;
+  const domHit = f.dom.has(d.getUTCDate());
+  const dowHit = f.dow.has(d.getUTCDay());
+  if (f.domRestricted && f.dowRestricted) return domHit || dowHit; // Vixie: either, when both are given
+  if (f.domRestricted) return domHit;
+  if (f.dowRestricted) return dowHit;
+  return true;
+}
+
+/** The first instant strictly after `afterMs` that the expression matches, in `tz`. */
+function nextCronMs(f, afterMs, tz) {
+  let local = Math.floor((afterMs + zoneOffsetMs(tz, afterMs)) / 60000) * 60000 + 60000;
+  const limit = local + 366 * 24 * 60 * 60 * 1000;
+  while (local <= limit) {
+    const d = new Date(local);
+    if (!matchesDay(f, d)) { local = Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate() + 1); continue; }
+    if (!f.hour.has(d.getUTCHours())) { local = Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate(), d.getUTCHours() + 1); continue; }
+    if (!f.minute.has(d.getUTCMinutes())) { local += 60000; continue; }
+    const utc = localToUtc(tz, local);
+    if (utc > afterMs) return utc;
+    local += 60000; // a wall-clock minute that repeats across a DST fall-back
+  }
+  return null;
+}
+
+/**
+ * The next run instant strictly after `after`, or null when the schedule is
+ * spent. `once` fires at `run_at` and then never again (a numeric `repeat`
+ * re-arms it — Hermes's "remaining runs"); `interval` counts from the last
+ * run, not from a fixed epoch; `cron` evaluates in `schedule.tz`, or without one in `zone` (the home's
+ * clock, `homeZone`).
+ */
+export function nextRunAt(schedule, after, zone = 'UTC') {
+  const afterMs = Date.parse(after);
+  if (!Number.isFinite(afterMs)) throw new TypeError(`nextRunAt: ${JSON.stringify(after)} is not an instant`);
+  switch (schedule?.kind) {
+    case 'once': {
+      const at = Date.parse(schedule.run_at);
+      return Number.isFinite(at) && at > afterMs ? new Date(at).toISOString() : null;
+    }
+    case 'interval':
+      return new Date(afterMs + schedule.minutes * 60000).toISOString();
+    case 'cron': {
+      checkZone(schedule.tz);
+      const ms = nextCronMs(parseCron(schedule.expr), afterMs, schedule.tz || zone);
+      return ms === null ? null : new Date(ms).toISOString();
+    }
+    default:
+      throw new TypeError(`nextRunAt: unknown schedule kind ${JSON.stringify(schedule?.kind)}`);
+  }
+}
+
+/**
+ * Why a schedule cannot be evaluated, or null when it can: a `once` that is
+ * not an instant, an `interval` that is not positive, a cron expression that
+ * does not parse or a zone that does not exist. Every door a job enters by
+ * refuses on this, and the tick disables a job it finds already holding one.
+ */
+export function scheduleError(schedule) {
+  switch (schedule?.kind) {
+    case 'once':
+      return Number.isFinite(Date.parse(schedule.run_at)) ? null : `schedule.run_at ${JSON.stringify(schedule.run_at)} is not an instant`;
+    case 'interval':
+      return schedule.minutes > 0 ? null : `schedule.minutes ${JSON.stringify(schedule.minutes)} is not a positive number`;
+    case 'cron':
+      try { parseCron(schedule.expr); checkZone(schedule.tz); return null; } catch (error) { return error.message; }
+    default:
+      return `schedule.kind ${JSON.stringify(schedule?.kind)} is not once | interval | cron`;
+  }
+}
+
+// ---------------------------------------------------------------- fires
+
+const two = (n) => String(n).padStart(2, '0');
+
+/** `YYYYMMDD_HHMMSS` in UTC — the stamp Hermes puts in a fire's session name. */
+export function compactStamp(at) {
+  const d = new Date(at);
+  return `${d.getUTCFullYear()}${two(d.getUTCMonth() + 1)}${two(d.getUTCDate())}_${two(d.getUTCHours())}${two(d.getUTCMinutes())}${two(d.getUTCSeconds())}`;
+}
+
+/** Hermes's fire session name: `cron_<job_id>_<YYYYMMDD_HHMMSS>` (UTC). */
+export function fireSessionName(jobId, at) {
+  return `cron_${jobId}_${compactStamp(at)}`;
+}
+
+/**
+ * A fire's id IS its session name, so the join survives the executions table
+ * unchanged (that table has no session column and the schema is frozen).
+ * `Fire.session_id` is set here for the live record; after a reload it is read
+ * back through this function.
+ */
+export function fireSessionId(fire) {
+  return fire.session_id ?? (/^cron_.+_\d{8}_\d{6}$/.test(fire.id) ? fire.id : null);
+}
+
+/** Enabled jobs that are due and have no fire in flight (the at-most-once guard). */
+export function dueJobs(profile, now) {
+  const t = Date.parse(now);
+  const inFlight = new Set(profile.fires.filter((f) => f.status === 'claimed' || f.status === 'running').map((f) => f.job_id));
+  return Object.values(profile.jobs)
+    .filter((j) => j.enabled && j.next_run_at && Date.parse(j.next_run_at) <= t && !inFlight.has(j.id))
+    .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+}
+
+/** Append the claim. Returns null when this exact fire already exists (a raced tick). */
+export function claimFire(profile, job, now) {
+  const id = fireSessionName(job.id, now);
+  if (profile.fires.some((f) => f.id === id)) return null;
+  const fire = {
+    id, job_id: job.id, session_id: id, status: 'claimed',
+    claimed_at: now, started_at: null, finished_at: null, error: null, obligation_id: null, residue: {},
+  };
+  profile.fires.push(fire);
+  return fire;
+}
+
+/**
+ * Close a fire and re-arm its job. `status` is `succeeded` | `failed` | `timeout`.
+ * A job that cannot be re-armed is disabled and its failure target told
+ * (`scheduleBroken`); with no `effects` to carry the send, the notice waits
+ * `pending` for the next tick's retry.
+ */
+export function finishFire(profile, fire, job, status, now, error = null, effects = null) {
+  fire.status = status;
+  fire.started_at ??= fire.claimed_at;
+  fire.finished_at = now;
+  fire.error = error;
+  if (!job) return fire;
+  // Hermes's scheduler records a failed run as an incident (`cron/incidents.py`), a run that went silent past
+  // its inactivity limit included; so does this loop
+  if ((status === 'failed' || status === 'timeout') && effects) effects.push({ type: 'record_incident', profile: profile.name, job_id: job.id, job_name: job.residue?.name ?? null, error: error ?? 'failed' });
+  // Hermes's \`mark_job_run\`: each run resets the delivery error; a delivery
+  // that then fails writes it again (the loop, when its obligation ends failed)
+  if (job.residue && 'last_delivery_error' in job.residue) job.residue.last_delivery_error = null;
+  job.last_run_at = fire.claimed_at;
+  job.last_status = status;
+  const broken = advanceSchedule(job, now, homeZone(profile));
+  if (broken) scheduleBroken(profile, job, broken, now, effects);
+  return fire;
+}
+
+/** Fail closed: the job is off, has no next run, and says why in Hermes's own `last_error`. */
+function disableJob(job, why) {
+  job.enabled = false;
+  job.next_run_at = null;
+  (job.residue ??= {}).last_error = why;
+  return why;
+}
+
+/**
+ * A job whose schedule cannot be evaluated never stays due: it is disabled
+ * (`disableJob`) and one notice goes to its failure target — `failure_deliver`,
+ * else `deliver`, else the profile's home. A target that is a file, or a home
+ * that is not set, leaves the notice in the daemon log only.
+ */
+function scheduleBroken(profile, job, why, now, effects) {
+  disableJob(job, why);
+  const text = `Cron job ${job.id} is disabled: its schedule cannot be evaluated (${why}). Correct the schedule and resume the job.`;
+  let target = resolveTarget(job, profile, job.failure_deliver ?? job.deliver ?? { kind: 'home' });
+  if (target.kind === 'local') target = resolveTarget(job, profile, { kind: 'home' });
+  effects?.push({ type: 'log', level: 'warn', message: text });
+  if (target.kind === 'local') return;
+  if (effects) reply(null, profile, target, text, now, effects);
+  else newObligation(profile, target, text, { kind: 'turn' }, now);
+  effects?.push({ type: 'save' });
+}
+
+/**
+ * `next_run_at` after a run. `repeat` is Hermes's `{times, completed}`
+ * (null times = forever): each run counts, a finite count that is reached
+ * spends the job. A `once` job re-arms only while a FINITE count has runs
+ * left — "forever" on a one-shot would refire every tick and is treated as
+ * spent (ORC-5). A schedule that cannot be evaluated fails closed: the job
+ * is disabled with no next run, and the reason is returned (null otherwise).
+ */
+export function advanceSchedule(job, now, zone = 'UTC') {
+  // every run counts, bounded or not: Hermes keeps `{times: null, completed}`
+  // on a job that repeats forever, and so does the record here
+  if (!job.repeat || typeof job.repeat !== 'object') job.repeat = { times: null, completed: 0 };
+  const rep = job.repeat;
+  if (rep) {
+    rep.completed = (rep.completed ?? 0) + 1;
+    if (rep.times !== null && rep.times !== undefined && rep.completed >= rep.times) { job.next_run_at = null; job.enabled = false; return null; }
+  }
+  if (job.schedule.kind === 'once') {
+    const again = rep && rep.times !== null && rep.times !== undefined && rep.completed < rep.times;
+    job.next_run_at = again ? now : null;
+    // a spent one-shot is done, not merely unscheduled: Hermes disables it
+    if (!again) job.enabled = false;
+    return null;
+  }
+  try {
+    job.next_run_at = nextRunAt(job.schedule, now, zone);
+  } catch (error) {
+    return disableJob(job, error.message);
+  }
+  return null;
+}
+
+/**
+ * A delivery `Target` resolved against the job and the profile:
+ * origin → `job.origin`, home → a home channel (Hermes's `platforms.<p>.home_channel`), a bare platform
+ * → that platform's home channel, as Hermes delivers `deliver: telegram`, explicit → as given,
+ * local → the sentinel `{kind:'local'}` (a file, not a chat).
+ */
+export function resolveTarget(job, profile, target = job?.deliver ?? null) {
+  const t = target ?? { kind: 'local' };
+  switch (t.kind) {
+    case 'origin': {
+      const o = job?.origin;
+      if (!o?.platform) return resolveTarget(job, profile, { kind: 'home' });
+      return chatKey(o.platform, o.chat_type, o.chat_id, o.thread_id);
+    }
+    case 'home': {
+      const h = homeChannel(profile);
+      if (!h) return { kind: 'local' };
+      return chatKey(h.platform, h.kind, h.chat_id, h.thread_id);
+    }
+    case 'explicit': {
+      if (!t.chat_id) {
+        // Hermes `_resolve_single_delivery_target`: the platform's home channel; else, for a job made on
+        // that platform, its origin chat; else no live delivery (the output is saved)
+        const h = homeChannel(profile, t.platform);
+        if (h) return chatKey(h.platform, h.kind, h.chat_id, h.thread_id);
+        const o = job?.origin;
+        if (o?.platform === t.platform && o.chat_id) return chatKey(o.platform, o.chat_type, o.chat_id, o.thread_id);
+        return { kind: 'local' };
+      }
+      return chatKey(t.platform, null, t.chat_id, t.thread_id);
+    }
+    case 'local':
+    default:
+      return { kind: 'local' };
+  }
+}
+
+/**
+ * Hermes `cron/scheduler.py` `_preflight_check_delivery`, transcribed: why a
+ * job's delivery target cannot be reached, or null. As there, `local`,
+ * `origin` and `home` need no check; an explicit platform the daemon runs no
+ * adapter for blocks the run, in Hermes's words. The adapters are the ones the
+ * loop connected at start (each reports up or down as it comes up).
+ */
+export function deliveryError(state, job, profile, spec = job?.deliver ?? null) {
+  if (spec?.kind !== 'explicit' || !spec.platform) return null;
+  const adapter = state.runtime?.adapters?.[spec.platform];
+  if (adapter && adapter.configured !== false) return null;
+  return `delivery platform '${spec.platform}' has no gateway credentials configured (not connected). Configure it via \`hermes setup\` or change the job's \`deliver\` target.`;
+}
+
+function chatKey(platform, chatType, chatId, threadId) {
+  const key = { platform, kind: chatType ?? 'dm' };
+  if (chatId) key.chat_id = String(chatId);
+  if (threadId) key.thread_id = String(threadId);
+  return key;
+}
+
+// ---------------------------------------------------------------- gates
+
+/**
+ * Hermes's pre-model fields, kept in the job's residue as its `jobs.json`
+ * holds them: `script` (stdout feeds the prompt, or IS the job with
+ * `no_agent`), `monitor_script` / `monitor_url` (hash-suppressed change
+ * detection, `cron/monitor.py`). Null when the job has none.
+ */
+export function jobGate(job) {
+  const r = job?.residue ?? {};
+  const text = (v) => (typeof v === 'string' && v.trim() ? v.trim() : null);
+  const gate = { script: text(r.script), no_agent: r.no_agent === true, monitor_script: text(r.monitor_script), monitor_url: text(r.monitor_url) };
+  return gate.script || gate.no_agent || gate.monitor_script || gate.monitor_url ? gate : null;
+}
+
+/**
+ * The gate fields a job door accepts, in Hermes's `create_job` names, checked
+ * by its rules and returned for the job's residue (empty when none is given).
+ */
+export function gateFields(args) {
+  const text = (v) => (typeof v === 'string' && v.trim() ? v.trim() : null);
+  const fields = {};
+  if (text(args.script)) fields.script = text(args.script);
+  if (args.no_agent !== undefined && Boolean(args.no_agent)) fields.no_agent = true;
+  if (text(args.monitor_script)) fields.monitor_script = text(args.monitor_script);
+  if (text(args.monitor_url)) fields.monitor_url = text(args.monitor_url);
+  const gate = jobGate({ residue: fields });
+  const broken = gate && gateError(gate);
+  if (broken) throw new Error(broken);
+  return fields;
+}
+
+/**
+ * Hermes `_validate_cron_script_path` (`tools/cronjob_tools.py`), the model's
+ * door only: a script is a path relative to the profile's scripts/ folder,
+ * never absolute, home-relative or escaping by `..`.
+ */
+export function scriptPathError(script) {
+  const raw = typeof script === 'string' ? script.trim() : '';
+  if (!raw) return null;
+  if (raw.startsWith('/') || raw.startsWith('~') || (raw.length >= 2 && raw[1] === ':')) {
+    return `Script path must be relative to the profile's scripts/ folder. Got absolute or home-relative path: ${JSON.stringify(raw)}. Place scripts in scripts/ and use just the filename.`;
+  }
+  const parts = [];
+  for (const part of raw.split(/[\\/]+/)) {
+    if (part === '..') { if (!parts.length) return `Script path escapes the scripts directory via traversal: ${JSON.stringify(raw)}`; parts.pop(); }
+    else if (part && part !== '.') parts.push(part);
+  }
+  return null;
+}
+
+/** Hermes's payload rule (`_PAYLOAD_FIELDS`): a job needs a prompt, a script, a skill, or no_agent with its script. */
+export function payloadError(args, gate) {
+  const prompt = typeof args.prompt === 'string' && args.prompt.trim();
+  const skills = Array.isArray(args.skills) && args.skills.some((s) => String(s).trim());
+  return prompt || gate.script || skills ? null : 'a job needs a prompt, a script or skills';
+}
+
+/** Hermes `create_job`'s combination rules (`cron/jobs.py:2181-2205`), refused by name. */
+export function gateError(gate) {
+  if (gate.monitor_script && gate.monitor_url) return 'monitor_script and monitor_url are mutually exclusive: a job watches one source';
+  if ((gate.monitor_script || gate.monitor_url) && gate.no_agent) return 'monitor_script/monitor_url cannot be combined with no_agent=True: a monitor decides whether the agent runs. Use a plain no_agent script job instead.';
+  if (gate.no_agent && !gate.script) return 'no_agent=True requires a script: with no agent and no script there is nothing to run';
+  return null;
+}
+
+/** Hermes `_parse_wake_gate`: a last stdout line `{"wakeAgent": false}` skips the agent. */
+export function wakes(output) {
+  const lines = String(output ?? '').split('\n').filter((l) => l.trim());
+  if (!lines.length) return true;
+  try {
+    const gate = JSON.parse(lines[lines.length - 1].trim());
+    return !(gate && typeof gate === 'object' && !Array.isArray(gate) && gate.wakeAgent === false);
+  } catch { return true; }
+}
+
+/**
+ * Hermes's blocked run (`run_job` preflight, `mark_preflight_alerted`): no
+ * model, `last_status: blocked_config`, the run's document saved every time,
+ * and its one alert (Hermes's words) delivered only on the first blocked run.
+ */
+function blockedFire(state, profile, job, fire, reason, now, effects) {
+  const alerted = job.residue?.preflight_alerted === true;
+  (job.residue ??= {}).preflight_alerted = true;
+  finishFire(profile, fire, job, 'failed', now, `${alerted ? '[blocked_config:silent]' : '[blocked_config]'} ${reason}`, effects);
+  job.last_status = 'blocked_config';
+  const name = job.residue?.name ?? job.id;
+  effects.push({ type: 'write_local', profile: profile.name, path: `cron/output/${job.id}/${compactStamp(now)}.md`, text: `# Cron Job: ${name}\n\n**Job ID:** ${job.id}\n**Run Time:** ${now}\n**Status:** BLOCKED (configuration)\n\nPre-dispatch validation found a configuration problem and the agent was NOT run (no tokens spent).\n\n**Reason:** ${reason}\n\nThe job will stay blocked (without re-alerting) until the configuration is fixed; the next healthy run clears this state.\n` });
+  const target = resolveTarget(job, profile, job.failure_deliver ?? job.deliver ?? null);
+  if (!alerted && target.kind !== 'local') {
+    const o = newObligation(profile, target, `⛔ Cron '${name}' blocked by configuration validation (no LLM call was made): ${reason} This alert is sent once; the job stays blocked until the configuration is fixed.`, { kind: 'fire', fire_id: fire.id }, now);
+    o.id = `obl-${fire.id}`;
+    fire.obligation_id = o.id;
+    effects.push({ type: 'deliver', profile: profile.name, obligation_id: o.id });
+  }
+  effects.push({ type: 'save' });
+}
+
+/** A run that ends without the model and without delivery: Hermes's SILENT runs. */
+function silentFire(profile, job, fire, status, now, effects) {
+  finishFire(profile, fire, job, 'succeeded', now, null, effects);
+  fire.residue = { ...(fire.residue ?? {}), status };
+  fire.obligation_id = null;
+  effects.push({ type: 'write_local', profile: profile.name, path: `cron/output/${job.id}/${compactStamp(now)}.md`, text: `# Cron Job: ${job.residue?.name ?? job.id}\n\n**Job ID:** ${job.id}\n**Run Time:** ${now}\n**Status:** ${status}\n` });
+  effects.push({ type: 'save' });
+}
+
+/**
+ * The gate's answer (`gate_result`), in Hermes's order (`run_job`): a
+ * `no_agent` job delivers its script's stdout (empty or `wakeAgent:false` is
+ * silent; a failure is an alert); a monitor that failed is an error, one that
+ * is unchanged is a silent `no_change`, one that changed puts its block in the
+ * prompt's Run Context; a pre-run script's stdout leads the prompt (empty or
+ * `wakeAgent:false` skips the model; a failure is reported to it).
+ */
+export function gateResult(state, ev, effects) {
+  const profile = state.profiles[ev.profile];
+  const rt = ensureRuntime(state);
+  delete rt.gates[`${ev.profile}:${ev.fire_id}`];
+  const fire = profile?.fires.find((f) => f.id === ev.fire_id);
+  if (!fire || fire.status !== 'running') return;
+  const job = profile.jobs[fire.job_id];
+  if (!job) { finishFire(profile, fire, null, 'failed', ev.at, 'the job was deleted while its gate ran', effects); return; }
+  const now = ev.at;
+  const name = job.residue?.name ?? job.id;
+  // the chat gets Hermes's one-line summary of the error (deliverResult); the error itself is the output
+  const fail = (why) => {
+    finishFire(profile, fire, job, 'failed', now, why, effects);
+    deliverResult(state, profile, { job, fire }, why, true, now, effects);
+  };
+  const script = ev.script ?? null;
+  if (jobGate(job)?.no_agent) {
+    if (!script?.ok) return fail(script?.output ?? 'the script did not run');
+    if (!wakes(script.output)) return silentFire(profile, job, fire, 'silent (wakeAgent=false)', now, effects);
+    if (!script.output.trim()) return silentFire(profile, job, fire, 'silent (empty output)', now, effects);
+    finishFire(profile, fire, job, 'succeeded', now, null, effects);
+    deliverResult(state, profile, { job, fire }, script.output, false, now, effects);
+    return;
+  }
+  let extra = null;
+  const monitor = ev.monitor ?? null;
+  if (monitor) {
+    if (!monitor.ok) return fail(monitor.error);
+    if (!monitor.changed) return silentFire(profile, job, fire, 'no_change (agent run suppressed)', now, effects);
+    // detection is the state boundary: persisted before the agent runs (the loop wrote the snapshot)
+    (job.residue ??= {}).monitor_state = { last_output_hash: monitor.hash, last_changed_at: now };
+    extra = monitor.block;
+  }
+  let prompt = firePrompt(job);
+  if (extra) prompt = `${prompt}\n\n## Run Context\n${extra}`;
+  if (script) {
+    if (script.ok && !script.output) return silentFire(profile, job, fire, 'silent (empty script output)', now, effects);
+    if (script.ok && !wakes(script.output)) return silentFire(profile, job, fire, 'silent (wakeAgent=false)', now, effects);
+    prompt = script.ok
+      ? `## Script Output\nThe following data was collected by a pre-run script. Use it as context for your analysis.\n\n\`\`\`\n${script.output}\n\`\`\`\n\n${prompt}`
+      : `## Script Error\nThe data-collection script failed. Report this to the user.\n\n\`\`\`\n${script.output}\n\`\`\`\n\n${prompt}`;
+  }
+  launchFire(state, profile, job, fire, prompt, now, effects);
+}
+
+// ---------------------------------------------------------------- history
+
+/** Hermes's `int(x) or None` for a count: a positive integer, else null. */
+function positiveInt(value) {
+  const n = cronNumber(value, 0);
+  return Math.trunc(n) > 0 ? Math.trunc(n) : null;
+}
+
+/**
+ * Hermes's own number parsing for a `cron:` key (`int(...)`/`float(...)` with
+ * the default on anything unreadable, null and "" included).
+ */
+function cronNumber(value, fallback) {
+  if (value === null || value === undefined || value === '' || typeof value === 'boolean') return fallback;
+  const n = Number(value);
+  return Number.isFinite(n) ? n : fallback;
+}
+
+/**
+ * Hermes's retention, transcribed:
+ * - `cron.output_retention` run files per job (50, `_prune_job_output`; the
+ *   loop prunes as it writes);
+ * - `cron.completed_retention_days` for a completed one-shot (7,
+ *   `_completed_oneshot_retention_days`);
+ * - the executions ledger keeps its newest 1000 terminal rows across every
+ *   job (`cron/executions.py` `MAX_TERMINAL_EXECUTIONS`, `_prune_unlocked`);
+ * - the delivery ledger drops delivered and abandoned rows older than 7 days,
+ *   then keeps at most 500 rows, removing delivered, then abandoned, then
+ *   pending, oldest first (`gateway/delivery_ledger.py` `_prune`).
+ * Zero or less disables the first two, as there.
+ */
+export const MAX_TERMINAL_FIRES = 1000;
+export const OBLIGATION_RETENTION_DAYS = 7;
+export const MAX_OBLIGATIONS = 500;
+
+export function historyRetention(profile) {
+  const cron = profile?.residue?.config?.cron ?? {};
+  return { outputs: Math.trunc(cronNumber(cron.output_retention, 50)), days: cronNumber(cron.completed_retention_days, 7) };
+}
+
+function pruneHistory(profile, now, effects) {
+  const { days } = historyRetention(profile);
+  const t = Date.parse(now);
+  let pruned = 0;
+  // completed one-shots (spent: disabled, nothing due, has run)
+  if (days > 0) {
+    const cutoff = t - days * 86_400_000;
+    for (const job of Object.values(profile.jobs)) {
+      const spent = job.schedule?.kind === 'once' && !job.enabled && !job.next_run_at && job.last_run_at;
+      if (spent && Date.parse(job.last_run_at) < cutoff) { delete profile.jobs[job.id]; pruned++; }
+    }
+  }
+  // the executions ledger: newest MAX_TERMINAL_FIRES terminal fires, in-flight ones always kept
+  const terminal = profile.fires.filter((f) => !['claimed', 'running'].includes(f.status));
+  if (terminal.length > MAX_TERMINAL_FIRES) {
+    const newest = (a, b) => (a.claimed_at === b.claimed_at ? (a.id < b.id ? 1 : -1) : a.claimed_at < b.claimed_at ? 1 : -1);
+    const drop = new Set(terminal.sort(newest).slice(MAX_TERMINAL_FIRES));
+    profile.fires = profile.fires.filter((f) => !drop.has(f));
+    pruned += drop.size;
+  }
+  // the delivery ledger (our `sent` is Hermes's delivered, `failed` its abandoned)
+  const before = profile.obligations.length;
+  const cutoff = t / 1000 - OBLIGATION_RETENTION_DAYS * 86_400;
+  profile.obligations = profile.obligations.filter((o) => !(['sent', 'failed'].includes(o.state) && Number(o.updated_at) < cutoff));
+  const excess = profile.obligations.length - MAX_OBLIGATIONS;
+  if (excess > 0) {
+    const rank = (o) => (o.state === 'sent' ? 0 : o.state === 'failed' ? 1 : 2);
+    const drop = new Set([...profile.obligations].sort((a, b) => rank(a) - rank(b) || Number(a.updated_at) - Number(b.updated_at)).slice(0, excess));
+    profile.obligations = profile.obligations.filter((o) => !drop.has(o));
+  }
+  pruned += before - profile.obligations.length;
+  if (pruned) effects.push({ type: 'save' });
+}
+
+// ---------------------------------------------------------------- the tick
+
+/**
+ * The cron half of `handleTick`: close breakers whose window passed, claim and
+ * run due jobs, and re-emit `deliver` for pending obligations whose backoff
+ * elapsed. Called by the reducer after the expiry half.
+ */
+export function cronTick(state, ev, effects) {
+  const now = ev.at;
+  const t = Date.parse(now);
+  const rt = ensureRuntime(state);
+  for (const adapter of Object.values(rt.adapters)) {
+    if (adapter.breaker?.until && t >= Date.parse(adapter.breaker.until)) adapter.breaker = { failures: 0 };
+  }
+  // Hermes's pool is one per process: the cap counts every profile's fires,
+  // from HERMES_CRON_MAX_PARALLEL, else the root profile's cron.max_parallel_jobs
+  const cap = ev.max_parallel ?? positiveInt(state.profiles.default?.residue?.config?.cron?.max_parallel_jobs);
+  const inFlight = () => Object.values(state.profiles).reduce((n, p) => n + p.fires.filter((f) => f.status === 'claimed' || f.status === 'running').length, 0);
+  for (const profile of Object.values(state.profiles)) {
+    reapStaleFires(state, profile, now, effects, ev.inactivity_s ?? 600);
+    pruneHistory(profile, now, effects);
+    for (const job of dueJobs(profile, now)) {
+      // past the cap, the rest stay due for the next tick (Hermes queues them
+      // in its pool within the tick); a job that starts nothing takes no slot
+      if (cap && inFlight() >= cap) break;
+      // a job that reached the folder by hand with a schedule nothing can
+      // evaluate is disabled before it runs, not after every run
+      const broken = scheduleError(job.schedule);
+      if (broken) scheduleBroken(profile, job, broken, now, effects);
+      else startFire(state, profile, job, now, effects);
+    }
+    retryObligations(state, profile, now, effects);
+  }
+}
+
+/**
+ * A fire whose session went away without a result — the expiry half of the same
+ * tick just ended it, say — is `timeout`, delivered like any other failure.
+ * Runs before the claim so a job unblocks on the same tick it times out.
+ */
+function reapStaleFires(state, profile, now, effects, limitS) {
+  const rt = ensureRuntime(state);
+  for (const fire of [...profile.fires]) {
+    if (fire.status !== 'claimed' && fire.status !== 'running') continue;
+    if (rt.hostedFires?.[`${profile.name}:${fire.id}`]) continue;
+    if (rt.gates[`${profile.name}:${fire.id}`]) continue; // its gate is still running (bounded by the script timeout)
+    // an ended binding lives under a started_at-qualified slot, so search by the fire it ran
+    const binding = Object.values(profile.bindings).find((b) => b.residue?.fire_id === fire.id);
+    if (binding && !binding.ended_at) {
+      // Hermes's inactivity watchdog, transcribed: a worker silent for the
+      // limit is a hung run. Without it the fire stays in flight and its job
+      // is never due again. Silence counts from the last worker event, the
+      // lease (a reattach after restart starts it afresh) or the claim.
+      if (!(limitS > 0)) continue;
+      const ks = surfaceKeyString(binding.key);
+      const lid = leaseId(profile.name, ks);
+      const lastAt = [rt.activity[lid], rt.leases[lid]?.since, fire.started_at, fire.claimed_at].filter(Boolean).sort().pop();
+      const idle = Math.round((Date.parse(now) - Date.parse(lastAt)) / 1000);
+      if (idle < limitS) continue;
+      const job = profile.jobs[fire.job_id] ?? null;
+      const why = `no activity from the worker for ${idle}s (limit ${limitS}s, HERMES_CRON_TIMEOUT; last activity ${lastAt}${rt.leases[lid] ? '' : ', the worker never started'}); the run was stopped`;
+      finishFire(profile, fire, job, 'timeout', now, why, effects);
+      deliverResult(state, profile, { job, fire, sub: null }, why, true, now, effects);
+      endBinding(state, profile.name, ks, 'error', now, effects); // the fire records the timeout; EndReason is closed
+      continue;
+    }
+    const job = profile.jobs[fire.job_id] ?? null;
+    const why = binding?.end_reason ? `the fire session ended (${binding.end_reason}) without a result`
+      : fire.residue?.gate && !binding ? 'the daemon restarted while the job\'s gate script ran; the run was abandoned'
+      : 'the fire session ended without a result';
+    finishFire(profile, fire, job, 'timeout', now, why, effects);
+    deliverResult(state, profile, { job, fire, sub: null }, why, true, now, effects);
+  }
+}
+
+/**
+ * The fire prompt is the job's prompt; `context_from` (job ids or "self") is
+ * carried beside it so the loop, which can read files, prepends those jobs'
+ * most recent output the way Hermes's scheduler does (`cron/scheduler.py:4823-4895`).
+ */
+function firePrompt(job) {
+  return job.prompt ?? '';
+}
+
+function startFire(state, profile, job, now, effects) {
+  const fire = claimFire(profile, job, now);
+  if (!fire) return;
+  effects.push({ type: 'save' }); // the claim is durable before anything runs (at-most-once)
+  if (state.runtime?.hostedJobs) {
+    fire.started_at = now;
+    fire.status = 'running';
+    fire.session_id = null; // a host callback is not a fabricated native worker session
+    fire.residue = { execution: 'host_task' };
+    state.runtime.hostedFires[`${profile.name}:${fire.id}`] = true;
+    effects.push({ type: 'save' });
+    effects.push({ type: 'execute_job', profile: profile.name, job_id: job.id, fire_id: fire.id });
+    return;
+  }
+  // A gate (a script, a monitor source) runs before any model, off the event
+  // queue: it may take Hermes's hour. Its answer comes back as `gate_result`.
+  const gate = jobGate(job);
+  if (gate) {
+    const broken = gateError(gate);
+    if (broken) {
+      finishFire(profile, fire, job, 'failed', now, broken, effects);
+      deliverResult(state, profile, { job, fire }, broken, true, now, effects);
+      return;
+    }
+    fire.started_at = now;
+    fire.status = 'running';
+    fire.residue = { ...(fire.residue ?? {}), gate: true };
+    ensureRuntime(state).gates[`${profile.name}:${fire.id}`] = true;
+    effects.push({ type: 'run_gate', profile: profile.name, job_id: job.id, fire_id: fire.id });
+    effects.push({ type: 'save' });
+    return;
+  }
+  launchFire(state, profile, job, fire, firePrompt(job), now, effects);
+}
+
+/**
+ * The fire's worker run: its own session, the prompt queued behind the lease.
+ * Hermes's delivery preflight runs here, after every gate (a silent script or
+ * monitor tick stays silent), just before a model would be paid for.
+ */
+function launchFire(state, profile, job, fire, prompt, now, effects) {
+  const undeliverable = deliveryError(state, job, profile);
+  if (undeliverable) { blockedFire(state, profile, job, fire, undeliverable, now, effects); return; }
+  if (job.residue && 'preflight_alerted' in job.residue) delete job.residue.preflight_alerted; // a healthy run clears it
+  if (!profile.worker) {
+    finishFire(profile, fire, job, 'failed', now, `profile ${profile.name} has no worker configured`, effects);
+    deliverResult(state, profile, { job, fire }, fire.error, true, now, effects);
+    return;
+  }
+  const rt = ensureRuntime(state);
+
+  const key = { platform: 'cron', kind: 'dm', chat_id: job.id };
+  const ks = surfaceKeyString(key);
+  endBinding(state, profile.name, ks, 'new', now, effects); // a previous fire never blocks this one
+  profile.bindings[ks] = {
+    key,
+    worker: { harness: profile.worker.harness, session_id: fire.id, locator: null },
+    started_at: now, last_activity_at: now, ended_at: null, end_reason: null,
+    handoff: null, recurrence: { job_id: job.id }, residue: { fire_id: fire.id },
+  };
+  fire.started_at = now;
+  const worker = { ...profile.worker, model: job.model ?? profile.worker.model, cwd: job.workdir ?? profile.worker.cwd };
+  // The prompt rides the queue: `handleWorker`'s `started` case flushes it once
+  // the lease exists, the same path an inbound message takes.
+  (rt.queues[leaseId(profile.name, ks)] ??= []).push({ text: prompt, at: now, context_from: job.context_from ?? null, skills: job.skills ?? [], job_id: job.id });
+  effects.push({ type: 'runtime_start', profile: profile.name, keyString: ks, worker, prompt });
+  effects.push({ type: 'save' });
+}
+
+function retryObligations(state, profile, now, effects) {
+  const rt = ensureRuntime(state);
+  const t = Date.parse(now);
+  for (const o of profile.obligations) {
+    if (o.state !== 'pending' || o.attempts >= MAX_ATTEMPTS) continue;
+    // A transport we already KNOW is down (an `adapter` event said so, §2.8)
+    // is the breaker-open case before the breaker has counted to three. Retry
+    // it and the whole outage is spent on one obligation's three attempts,
+    // which then dies `failed` while the adapter is still down and is never
+    // sent — the one thing the breaker exists to prevent (ORC-8, day four).
+    if (rt.adapters[o.target.platform]?.state === 'down') continue;
+    const breaker = rt.adapters[o.target.platform]?.breaker;
+    if (breaker?.until && t < Date.parse(breaker.until)) continue; // open: pending, untouched
+    const wait = o.attempts === 0 ? 0 : BACKOFF_MINUTES[Math.min(o.attempts, BACKOFF_MINUTES.length) - 1] * 60000;
+    if (t - Number(o.updated_at) * 1000 < wait) continue;
+    effects.push({ type: 'deliver', profile: profile.name, obligation_id: o.id });
+  }
+}
+
+// ---------------------------------------------------------------- worker events on a fire's session
+
+export const isSynthetic = (binding) => Boolean(binding?.recurrence || binding?.residue?.webhook);
+
+function contextOf(profile, binding) {
+  if (binding.recurrence) {
+    const job = profile.jobs[binding.recurrence.job_id] ?? null;
+    const fire = profile.fires.find((f) => f.id === binding.residue?.fire_id)
+      ?? [...profile.fires].reverse().find((f) => f.job_id === binding.recurrence.job_id && (f.status === 'claimed' || f.status === 'running'))
+      ?? null;
+    return { job, fire, sub: null };
+  }
+  return { job: null, fire: null, sub: profile.subscriptions[binding.residue.webhook] ?? null };
+}
+
+/**
+ * A permission request on a fire's or a webhook turn's session has nobody to
+ * answer it — the synthetic surface has no adapter and no reader — so it is
+ * decided at once rather than left to `worker.permission.timeout_seconds`.
+ * Hermes's `approvals.cron_mode`, transcribed: `worker.permission.unattended`
+ * is `deny` unless it says `approve`, and the worker's matching option is
+ * chosen the way the timeout chooses one. One line saying what was decided
+ * goes to the job's `failure_deliver`, else `deliver`, else home (a webhook's:
+ * the subscription's `deliver`). Returns false for a chat binding, whose
+ * prompt is relayed (§4.2).
+ */
+export function unattendedRequest(state, profile, binding, keyString, request, now, effects) {
+  if (!isSynthetic(binding)) return false;
+  // Hermes's `approvals.cron_mode` when Hermes judged the request, else the worker's own setting
+  const mode = request.hermes?.verdict === 'deny' ? 'deny' : profile.worker?.permission?.unattended === 'approve' ? 'approve' : 'deny';
+  effects.push({ type: 'respond', profile: profile.name, keyString, request_id: String(request.id), response: permissionResponse(request.options, mode === 'approve', request.hermes?.message ?? `Denied: nobody is attending this run to approve it (worker.permission.unattended: ${mode}). Find an alternative approach that avoids this action.`) });
+  const { job, fire, sub } = contextOf(profile, binding);
+  const subject = String(request.subject ?? 'a tool call').replace(/\s+/g, ' ').slice(0, 200);
+  const who = job ? `Cron job ${job.id}` : `Webhook ${sub?.name ?? binding.residue?.webhook ?? ''}`;
+  const rule = request.hermes?.verdict === 'deny' ? `Hermes: ${request.hermes.why ?? 'a dangerous command'}` : `worker.permission.unattended: ${mode}`;
+  const text = `${who}: ${mode === 'approve' ? 'approved' : 'denied'} a permission request with nobody attending (${rule}): ${subject}`;
+  let target = resolveTarget(job, profile, job ? (job.failure_deliver ?? job.deliver ?? { kind: 'home' }) : (sub?.deliver ?? { kind: 'home' }));
+  if (target.kind === 'local') target = resolveTarget(job, profile, { kind: 'home' });
+  if (target.kind === 'local') {
+    effects.push({ type: 'log', level: 'info', message: text });
+    return true;
+  }
+  reply(state, profile, target, text, now, effects, fire ? { kind: 'fire', fire_id: fire.id } : { kind: 'webhook', name: sub?.name ?? '' });
+  effects.push({ type: 'save' });
+  return true;
+}
+
+/**
+ * The `final` of a fire's (or a webhook turn's) own session: the obligation is
+ * created on the job's resolved delivery target, never on the synthetic key.
+ * Returns false when the binding is an ordinary conversation.
+ */
+export function fireFinal(state, profile, binding, text, now, effects) {
+  if (!isSynthetic(binding)) return false;
+  const ctx = contextOf(profile, binding);
+  if (ctx.fire) finishFire(profile, ctx.fire, ctx.job, 'succeeded', now, null, effects);
+  deliverResult(state, profile, ctx, text, false, now, effects);
+  if (binding.recurrence) endBinding(state, profile.name, surfaceKeyString(binding.key), 'new', now, effects);
+  return true;
+}
+
+/** `error` / `ended` on a fire's session: `failure_deliver`, else `deliver` with a prefix. */
+export function fireFailed(state, profile, binding, message, now, effects) {
+  if (!isSynthetic(binding)) return false;
+  const ctx = contextOf(profile, binding);
+  if (ctx.fire) finishFire(profile, ctx.fire, ctx.job, 'failed', now, message, effects);
+  deliverResult(state, profile, ctx, message, true, now, effects);
+  return true;
+}
+
+function deliverResult(state, profile, ctx, text, failed, now, effects) {
+  const { job, fire, sub } = ctx;
+  const said = text || '(no output)';
+  const body = failed && job ? summarizeFailure(job, said) : failed ? `Failed:\n\n${said}` : said;
+  const spec = failed
+    ? (job?.failure_deliver ?? job?.deliver ?? sub?.deliver ?? null)
+    : (job?.deliver ?? sub?.deliver ?? null);
+  const target = resolveTarget(job, profile, spec);
+  // Hermes `save_job_output` (`cron/jobs.py:4467`): every fire's output is
+  // saved under `cron/output/<job_id>/<stamp>.md`, which is what a later
+  // `context_from` reads. `local` delivery is that file and nothing more.
+  if (fire && job) {
+    effects.push({ type: 'write_local', profile: profile.name, path: `cron/output/${job.id}/${compactStamp(now)}.md`, text: said });
+  }
+  // a silence marker is kept in the output file and never delivered (Hermes's autonomous lanes)
+  if (!failed && isSilence(text)) {
+    if (fire) fire.obligation_id = null;
+    effects.push({ type: 'save' });
+    return null;
+  }
+  if (target.kind === 'local') {
+    if (!fire) effects.push({ type: 'write_local', profile: profile.name, path: `cron/output/webhook_${sub?.name ?? 'unknown'}_${compactStamp(now)}.md`, text: body });
+    if (fire) fire.obligation_id = null;
+    effects.push({ type: 'save' });
+    return null;
+  }
+  const source = fire ? { kind: 'fire', fire_id: fire.id } : { kind: 'webhook', name: sub?.name ?? '' };
+  const o = newObligation(profile, target, body, source, now);
+  if (fire) { o.id = `obl-${fire.id}`; fire.obligation_id = o.id; }
+  effects.push({ type: 'deliver', profile: profile.name, obligation_id: o.id });
+  effects.push({ type: 'save' });
+  return o;
+}
+
+/** A hosted task confirms dispatch/action execution, never a model's eventual answer. */
+export function finishHostedFire(state, event, effects) {
+  const profile = state.profiles[event.profile];
+  const fire = profile?.fires.find((f) => f.id === event.fire_id);
+  if (!fire || !['claimed', 'running'].includes(fire.status)) return;
+  delete state.runtime.hostedFires[`${profile.name}:${fire.id}`];
+  const job = profile.jobs[fire.job_id];
+  finishFire(profile, fire, job, event.error ? 'failed' : 'succeeded', event.at, event.error ?? null, effects);
+  const text = event.error || event.receipt.output;
+  fire.residue.host_receipt = event.receipt ?? null;
+  const delivery = event.receipt?.delivery;
+  if (!event.error && delivery?.platform && delivery?.id) {
+    const obligation = newObligation(profile, { platform: delivery.platform, kind: 'dm', chat_id: delivery.chat_id || profile.name }, text, { kind: 'fire', fire_id: fire.id }, event.at);
+    obligation.state = 'sent';
+    obligation.attempts = 1;
+    obligation.delivered_at = obligation.updated_at;
+    obligation.posted = { message_id: delivery.id };
+    obligation.residue.native_id = delivery.id;
+    fire.obligation_id = obligation.id;
+  }
+  effects.push({ type: 'write_local', profile: profile.name, path: `cron/output/${fire.job_id}/${compactStamp(event.at)}.md`, text });
+  effects.push({ type: 'save' });
+}