@volter/supercode-orchestrator 0.4.4

package/reducer.mjs

@@ -0,0 +1,792 @@
+// The loop as a pure reducer (docs/ORCHESTRATOR-IR.md §4).
+//
+//   step(state, event) -> Effect[]
+//
+// Mutates `state` in place (it is the orchestrator's single value) and emits
+// effects (§5). It never performs I/O and imports no node module: the test
+// suite asserts that statically. Time comes from the event's `at`.
+
+import { surfaceKeyString, renderSurfaceKey, resolveRoute, sessionReset, homeChannel } from './ir.mjs';
+import { parseCommand, frame, REPLY } from './commands.mjs';
+import { cronTick, gateResult, fireFinal, fireFailed, finishHostedFire, homeZone, isSynthetic, nextRunAt, scheduleError, unattendedRequest } from './cron.mjs';
+import { handleWebhook } from './webhook.mjs';
+import { modelError } from './activation.mjs';
+
+export function keyOf(event) {
+  return surfaceKeyString(event.key);
+}
+
+function profileOf(state, name) {
+  const p = state.profiles[name];
+  if (!p) throw new Error(`unknown profile ${name}`);
+  return p;
+}
+
+export function ensureRuntime(state) {
+  const r = state.runtime;
+  r.leases ??= {}; r.queues ??= {}; r.adapters ??= {}; r.pending_requests ??= {}; r.turns ??= {}; r.starting ??= {}; r.activity ??= {}; r.gates ??= {};
+  return r;
+}
+
+function leaseId(profile, keyString) {
+  return `${profile} ${keyString}`;
+}
+
+// ---------------------------------------------------------------- expiry
+
+function minutesBetween(a, b) {
+  return (Date.parse(b) - Date.parse(a)) / 60000;
+}
+
+/** A daily boundary at local `hour` lies in (a, b] (Hermes resets at a local hour). */
+function crossedDailyBoundary(a, b, hour) {
+  const start = new Date(a);
+  const boundary = new Date(start.getFullYear(), start.getMonth(), start.getDate(), hour, 0, 0, 0);
+  if (boundary <= start) boundary.setDate(boundary.getDate() + 1);
+  return boundary.getTime() <= Date.parse(b);
+}
+
+/** Whether a session has reset, by Hermes's `session_reset` (`sessionReset`): its end reason, or null. */
+export function expired(binding, reset, now) {
+  if (binding.ended_at) return binding.end_reason ?? 'reset';
+  const idle = reset.mode === 'idle' || reset.mode === 'both';
+  const daily = reset.mode === 'daily' || reset.mode === 'both';
+  if (idle && minutesBetween(binding.last_activity_at, now) >= reset.idle_minutes) return 'idle';
+  if (daily && crossedDailyBoundary(binding.last_activity_at, now, reset.at_hour)) return 'daily';
+  return null;
+}
+
+export function liveBinding(profile, keyString) {
+  const b = profile.bindings[keyString];
+  return b && !b.ended_at ? b : null;
+}
+
+// ---------------------------------------------------------------- access
+
+/**
+ * Hermes's `_get_unauthorized_dm_behavior`, transcribed: a platform's own `unauthorized_dm_behavior`,
+ * email ignored, a global override, the platform's `dm_policy`, then `ignore` where an allowlist is
+ * configured and `pair` on an open gateway.
+ */
+export function dmBehavior(profile, platform) {
+  const extra = profile.channels?.[platform]?.extra ?? {};
+  const own = extra['extra.unauthorized_dm_behavior'] ?? extra.unauthorized_dm_behavior;
+  if (own) return String(own);
+  if (platform === 'email') return 'ignore';
+  const global = profile.residue?.config?.unauthorized_dm_behavior;
+  if (global && global !== 'pair') return String(global);
+  const policy = String(extra['extra.dm_policy'] ?? extra.dm_policy ?? '').trim().toLowerCase();
+  if (policy === 'pairing') return 'pair';
+  if (policy === 'allowlist' || policy === 'disabled') return 'ignore';
+  return (profile.access.allowlist[platform] ?? []).length ? 'ignore' : 'pair';
+}
+
+/** §4.1 step 1: a platform with no `policy` entry is `allowlist`, never open. */
+export function accessPolicy(profile, platform) {
+  return profile.access.policy[platform] ?? 'allowlist';
+}
+
+
+export function endBinding(state, profileName, keyString, reason, now, effects) {
+  const profile = state.profiles[profileName];
+  const b = profile.bindings[keyString];
+  if (!b || b.ended_at) return;
+  b.ended_at = now;
+  b.end_reason = reason;
+  if (b.residue) delete b.residue.runtime_id; // the lease is gone with the binding (§4.7)
+  // ended bindings keep their history under a started_at-qualified slot;
+  // two sessions ended within one clock instant get distinct slots
+  delete profile.bindings[keyString];
+  let slot = `${keyString}#${b.started_at}`;
+  for (let n = 2; profile.bindings[slot]; n++) slot = `${keyString}#${b.started_at}#${n}`;
+  profile.bindings[slot] = b;
+  const rt = ensureRuntime(state);
+  const lid = leaseId(profileName, keyString);
+  if (rt.leases[lid]) { effects.push({ type: 'runtime_close', profile: profileName, keyString, lease: rt.leases[lid] }); delete rt.leases[lid]; }
+  delete rt.turns[lid];
+  delete rt.queues[lid];
+  delete rt.activity[lid];
+}
+
+// ---------------------------------------------------------------- obligations
+
+let obligationCounter = 0;
+export function newObligation(profile, key, text, source, now) {
+  // The stamp is a second and the counter is per PROCESS, so a daemon that
+  // came back inside the same second as the last one would otherwise mint an
+  // id the store already holds (`delivery_obligations.obligation_id` is
+  // unique). The profile's own rows are the authority on what is taken.
+  const stamp = now.replace(/[^0-9]/g, '').slice(0, 14);
+  let id = `obl-${stamp}-${(++obligationCounter).toString(36)}`;
+  while (profile.obligations.some((o) => o.id === id)) id = `obl-${stamp}-${(++obligationCounter).toString(36)}`;
+  const o = {
+    id,
+    target: { platform: key.platform, kind: key.kind, chat_id: key.chat_id ?? '', thread_id: key.thread_id ?? null },
+    session_key: renderSurfaceKey(profile.name, key),
+    content: { text },
+    state: 'pending', attempts: 0, last_error: null,
+    created_at: String(Date.parse(now) / 1000), updated_at: String(Date.parse(now) / 1000), delivered_at: null,
+    source, residue: {},
+  };
+  profile.obligations.push(o);
+  return o;
+}
+
+export function reply(state, profile, key, text, now, effects, source = { kind: 'turn' }) {
+  const o = newObligation(profile, key, text, source, now);
+  effects.push({ type: 'deliver', profile: profile.name, obligation_id: o.id });
+  return o;
+}
+
+// ---------------------------------------------------------------- inbound
+
+function handleInbound(state, ev, effects) {
+  const owner = profileOf(state, ev.profile);
+  const now = ev.at;
+
+  // 0. our own echo (§3 `is_me`): a platform that replays what we just posted
+  // is not a turn. Answering it would loop the conversation against itself.
+  if (ev.is_me) return;
+
+  // 1. access
+  const policy = accessPolicy(owner, ev.key.platform);
+  const allowed = policy === 'open' || (owner.access.allowlist[ev.key.platform] ?? []).includes(ev.sender);
+  if (!allowed) {
+    // Hermes's gateway: in a DM whose platform pairs, a stranger is offered a code from Hermes's own
+    // pairing store (its codes, expiry, rate limit and lockout; docs/plans/hermes-compat.md row 8);
+    // anywhere else, and wherever the owner restricted access, the message is dropped silently
+    if (ev.key.kind === 'dm' && dmBehavior(owner, ev.key.platform) === 'pair') {
+      effects.push({ type: 'pairing_issue', profile: owner.name, platform: ev.key.platform, user_id: ev.sender, user_name: ev.sender_name ?? '', key: ev.key });
+    } else {
+      effects.push({ type: 'log', level: 'info', message: `unauthorized ${ev.key.platform} sender ${ev.sender} ignored` });
+    }
+    return;
+  }
+
+  // 2. route
+  const routed = resolveRoute(owner.routes, ev.key, ev.guild_id) ?? owner.name;
+  const profile = profileOf(state, routed);
+  const keyString = keyOf(ev);
+
+  // 3. command
+  const cmd = parseCommand(ev.text);
+  if (cmd) { handleCommand(state, profile, ev, keyString, cmd, effects); return; }
+
+  // 4. get-or-create
+  let b = liveBinding(profile, keyString);
+  if (b) {
+    const reason = expired(b, sessionReset(profile), now);
+    if (reason) { endBinding(state, profile.name, keyString, reason, now, effects); b = null; }
+  }
+  if (!b) {
+    b = {
+      key: ev.key,
+      worker: { harness: profile.worker?.harness ?? 'unknown', session_id: null, locator: null },
+      started_at: now, last_activity_at: now, ended_at: null, end_reason: null, handoff: null, recurrence: null, residue: {},
+    };
+    profile.bindings[keyString] = b;
+    if (!profile.worker) { reply(state, profile, ev.key, `Profile ${profile.name} has no worker configured.`, now, effects); return; }
+    startWorker(state, profile, keyString, effects);
+  } else {
+    // A live binding whose lease is gone — a restart, a worker that died — must
+    // get its worker back on the next message rather than queue it forever
+    // (ORC-8 finding: "a resent message after a restart is never answered").
+    const rt0 = ensureRuntime(state);
+    const lid0 = leaseId(profile.name, keyString);
+    if (!rt0.leases[lid0] && !rt0.turns[lid0] && !rt0.starting[lid0] && profile.worker) {
+      if (b.worker.session_id) {
+        b.residue.resumed_from = b.worker.session_id;
+        // The conversation's session comes back, not a blank one; one that will not reopen starts fresh (loop).
+        b.residue.resume_runtime_id ??= b.residue.runtime_id ?? b.worker.session_id;
+      }
+      startWorker(state, profile, keyString, effects);
+    }
+  }
+  b.last_activity_at = now;
+
+  // 5. frame and send, or queue behind the running turn
+  const rt = ensureRuntime(state);
+  const lid = leaseId(profile.name, keyString);
+  const text = frame(profile.name, ev.key, ev.sender, ev.sender_name, now, ev.text);
+  const inFlight = Boolean(rt.turns[lid]);
+  const leased = Boolean(rt.leases[lid]);
+  if (inFlight && leased && rt.leases[lid].steer) {
+    // A worker that takes input mid-turn (the harness's `steer`) hears the line now, inside the turn it is running:
+    // a person steering a long piece of work is not held until the work is done. Its reply is that turn's.
+    effects.push({ type: 'steer_input', profile: profile.name, keyString, text });
+  } else if (inFlight || !leased) {
+    (rt.queues[lid] ??= []).push({ text, at: now });
+  } else {
+    rt.turns[lid] = { started_at: now, buffer: '' };
+    effects.push({ type: 'send_input', profile: profile.name, keyString, text });
+  }
+  effects.push({ type: 'save' });
+}
+
+/**
+ * Emit one `runtime_start` for a surface and remember that it is starting, so
+ * a burst of messages before the lease exists queues behind ONE start (the
+ * `started`/`error` worker events clear the mark).
+ */
+function startWorker(state, profile, keyString, effects) {
+  const rt = ensureRuntime(state);
+  rt.starting[leaseId(profile.name, keyString)] = true;
+  // A binding whose runtime went away with the daemon reopens that same session where its harness can, so the
+  // conversation it held is not lost; the loop starts fresh when the harness cannot.
+  const resume = profile.bindings[keyString]?.residue?.resume_runtime_id ?? null;
+  effects.push({ type: 'runtime_start', profile: profile.name, keyString, worker: profile.worker, prompt: null, resume_runtime_id: resume });
+}
+
+
+// ---------------------------------------------------------------- commands
+
+function handleCommand(state, profile, ev, keyString, cmd, effects) {
+  const now = ev.at;
+  switch (cmd.name) {
+    case 'new':
+    case 'reset': {
+      endBinding(state, profile.name, keyString, cmd.name, now, effects);
+      reply(state, profile, ev.key, cmd.name === 'new' ? REPLY.newSession : REPLY.reset, now, effects);
+      break;
+    }
+    case 'sethome': {
+      // Hermes's `/sethome`: the platform's `home_channel` in its `platforms:` block
+      const channel = (profile.channels[ev.key.platform] ??= { platform: ev.key.platform, enabled: true, credentials: {}, extra: {} });
+      channel.extra = { ...(channel.extra ?? {}), home_channel: { platform: ev.key.platform, chat_id: ev.key.chat_id ?? '', name: ev.sender_name ?? ev.key.chat_id ?? '', ...(ev.key.thread_id ? { thread_id: ev.key.thread_id } : {}) } };
+      effects.push({ type: 'save' });
+      reply(state, profile, ev.key, REPLY.homeSet, now, effects);
+      break;
+    }
+    case 'status': {
+      const b = liveBinding(profile, keyString);
+      const lines = [
+        `profile: ${profile.name}`,
+        `worker: ${profile.worker ? profile.worker.harness + (profile.worker.model ? ` (${profile.worker.model})` : '') : 'none'}`,
+        `session: ${b ? b.worker.session_id || 'starting' : 'none'}`,
+        `session reset: ${(({ mode, at_hour, idle_minutes }) => (mode === 'none' ? 'none' : [mode !== 'daily' ? `idle ${idle_minutes} min` : null, mode !== 'idle' ? `daily at ${at_hour}:00` : null].filter(Boolean).join(', ')))(sessionReset(profile))}`,
+        `queued: ${(ensureRuntime(state).queues[leaseId(profile.name, keyString)] ?? []).length}`,
+      ];
+      reply(state, profile, ev.key, lines.join('\n'), now, effects);
+      break;
+    }
+    case 'whoami': {
+      reply(state, profile, ev.key, `${ev.sender}${ev.sender_name ? ` (${ev.sender_name})` : ''} on ${renderSurfaceKey(profile.name, ev.key)}`, now, effects);
+      break;
+    }
+    case 'model': {
+      if (!profile.worker) { reply(state, profile, ev.key, `Profile ${profile.name} has no worker configured.`, now, effects); break; }
+      // refused here, not at the next start, where it would end every conversation
+      const unusable = modelError(profile.worker.harness, cmd.args);
+      if (unusable) { reply(state, profile, ev.key, `Model not changed: ${unusable}.`, now, effects); break; }
+      const b = liveBinding(profile, keyString);
+      if (b) b.residue.model_override = cmd.args;
+      profile.worker.model = cmd.args || null;
+      reply(state, profile, ev.key, REPLY.modelApplied(cmd.args || 'default'), now, effects);
+      effects.push({ type: 'save' });
+      break;
+    }
+    case 'sessions': {
+      const rows = Object.values(profile.bindings).filter((b) => surfaceKeyString(b.key) === keyString).sort((a, b) => (a.started_at < b.started_at ? 1 : -1)).slice(0, 10);
+      const text = rows.length ? rows.map((b, i) => `${i + 1}. ${b.worker.session_id || '(starting)'} · ${b.started_at}${b.ended_at ? ` · ended (${b.end_reason})` : ' · live'}`).join('\n') : 'No sessions on this surface.';
+      reply(state, profile, ev.key, text, now, effects);
+      break;
+    }
+    case 'handoff': {
+      const outcome = doHandoff(state, profile, keyString, cmd.args || null, null, now, effects);
+      reply(state, profile, ev.key, outcome.message, now, effects);
+      break;
+    }
+    case 'bg': {
+      const id = `bg-${now.replace(/[^0-9]/g, '').slice(0, 14)}`;
+      profile.jobs[id] = {
+        id, schedule: { kind: 'once', run_at: now }, prompt: cmd.args, workdir: null, model: null, skills: [], context_from: null,
+        deliver: { kind: 'origin' }, failure_deliver: { kind: 'origin' },
+        origin: { platform: ev.key.platform, chat_type: ev.key.kind, chat_id: ev.key.chat_id ?? null, thread_id: ev.key.thread_id ?? null },
+        attach_to_session: null, repeat: null, enabled: true, next_run_at: now, last_run_at: null, last_status: null, created_at: now, residue: {},
+      };
+      reply(state, profile, ev.key, REPLY.bgQueued(id), now, effects);
+      effects.push({ type: 'save' });
+      break;
+    }
+    default:
+      break;
+  }
+}
+
+/**
+ * `/handoff <platform>` and the `session_handoff` tool share this (§4.5): mark
+ * the live binding pending, announce it on the profile's home chat on that
+ * platform, or fail by name when there is none. Returns what to tell the caller.
+ */
+export function doHandoff(state, profile, keyString, to, note, now, effects) {
+  const b = liveBinding(profile, keyString);
+  if (!b) return { ok: false, message: 'No live session to hand off.' };
+  if (!to) return { ok: false, message: 'Cannot hand off: no platform named.' };
+  b.handoff = { to, state: 'pending', error: null };
+  const target = homeChannel(profile, to);
+  if (target) {
+    reply(state, profile, target, `Continuing session ${b.worker.session_id} from ${b.key.platform}. Reply here to pick it up.${note ? `\n${note}` : ''}`, now, effects);
+  } else {
+    b.handoff.state = 'failed';
+    b.handoff.error = `no home chat on ${to}`;
+  }
+  effects.push({ type: 'save' });
+  return b.handoff.state === 'pending'
+    ? { ok: true, message: `Handed off to ${to}.` }
+    : { ok: false, message: `Cannot hand off: ${b.handoff.error}.` };
+}
+
+// ---------------------------------------------------------------- worker events
+
+function handleWorker(state, ev, effects) {
+  const profile = profileOf(state, ev.profile);
+  const rt = ensureRuntime(state);
+  const lid = leaseId(profile.name, ev.keyString);
+  const binding = liveBinding(profile, ev.keyString);
+  const now = ev.at;
+  const w = ev.ev;
+  // A runtime that no longer serves this surface (the one a timed-out fire's
+  // binding closed, while the next fire starts on the same key) is not heard:
+  // its late `closed` would otherwise fail the new fire.
+  if (w.kind !== 'started' && ev.runtime_id) {
+    const current = rt.leases[lid]?.runtime_id ?? binding?.residue?.runtime_id ?? null;
+    if (current !== ev.runtime_id) return;
+  }
+  // any word from the worker is activity; a fire's inactivity limit counts from the last (§4.3)
+  rt.activity[lid] = now;
+  switch (w.kind) {
+    case 'activity':
+      break;
+    case 'started': {
+      delete rt.starting[lid];
+      // A runtime whose binding ended while it was starting (/new, /reset or
+      // idle expiry during boot) is closed: nothing will use it.
+      // A reattach whose binding was replaced while it attached (a cron fire,
+      // /new then a message) is not that binding's runtime either.
+      if (!binding || (w.reattach_of && binding.residue?.runtime_id !== w.reattach_of)) {
+        effects.push({ type: 'runtime_close', profile: profile.name, keyString: ev.keyString, runtime_id: w.runtime_id });
+        break;
+      }
+      // Starts run one at a time, so a `started` is always the newest runtime
+      // on this surface (the loop has already made it the one it sends to).
+      // It takes the lease; the runtime it displaces is closed by name.
+      if (rt.leases[lid] && rt.leases[lid].runtime_id !== w.runtime_id) {
+        effects.push({ type: 'runtime_close', profile: profile.name, keyString: ev.keyString, runtime_id: rt.leases[lid].runtime_id });
+      }
+      delete rt.starting[lid];
+      rt.leases[lid] = { runtime_id: w.runtime_id, connection: w.connection ?? null, since: now, steer: w.steer === true };
+      if (binding) {
+        binding.worker.session_id = w.session_id ?? w.runtime_id;
+        binding.worker.harness = w.harness ?? binding.worker.harness;
+        // §2.8 never persists the lease table, so the binding carries the one
+        // fact a restart needs from it: which runtime was serving this surface.
+        binding.residue.runtime_id = w.runtime_id;
+        delete binding.residue.interrupted_at;
+      }
+      // the first queued message goes out now that the lease exists
+      const q = rt.queues[lid] ?? [];
+      if (q.length && !rt.turns[lid]) {
+        const next = q.shift();
+        rt.turns[lid] = { started_at: now, buffer: '' };
+        effects.push(queuedInput(profile.name, ev.keyString, next));
+      }
+      effects.push({ type: 'save' });
+      break;
+    }
+    case 'steer_refused': {
+      // The harness would not take the line mid-turn: it waits for the turn's end like any other.
+      (rt.queues[lid] ??= []).push({ text: w.text, at: now });
+      break;
+    }
+    case 'text': {
+      const t = rt.turns[lid] ??= { started_at: now, buffer: '' };
+      // A conversation hears a working turn as it goes: a whole message is delivered as it arrives. Once the turn has
+      // spoken through the tool, a message waits for the next, since the last one is narration of that reply (§4.2
+      // `final`). A fire's session delivers once.
+      if (w.block && binding && !isSynthetic(binding)) {
+        if (t.buffer.trim()) reply(state, profile, binding.key, t.buffer.trim(), now, effects);
+        t.buffer = '';
+        if (!t.replied && (w.delta ?? '').trim()) {
+          reply(state, profile, binding.key, w.delta.trim(), now, effects);
+          effects.push({ type: 'save' });
+          break;
+        }
+        effects.push({ type: 'save' });
+      }
+      // Whole messages are paragraphs; streamed chunks continue the text they belong to, and a chunk of another
+      // message starts a paragraph (a fire's report read "…the raw results.1) Shell output…" without it).
+      const newMessage = !w.block && w.item && t.item && w.item !== t.item;
+      if ((w.block || newMessage) && t.buffer && !t.buffer.endsWith('\n')) t.buffer += '\n\n';
+      if (w.item) t.item = w.item;
+      t.buffer += w.delta ?? '';
+      // the turn's last message alone: what a fire delivers, as Hermes delivers a fire's final response
+      t.last = w.block || newMessage || t.last === undefined ? (w.delta ?? '') : t.last + (w.delta ?? '');
+      break;
+    }
+    case 'final': {
+      const t = rt.turns[lid];
+      const text = (w.text ?? t?.buffer ?? '').trim();
+      delete rt.turns[lid];
+      if (binding) binding.last_activity_at = now;
+      // a turn that ended in error (§4.2; the SDK's `turn_completed` with
+      // `outcome: error`) FAILS a fire and tells a chat surface once — it is
+      // never mistaken for an empty answer (ORC-8 finding)
+      const failed = w.outcome === 'error';
+      const message = w.message ?? 'the worker reported an error';
+      // a fire's (or a webhook turn's) session delivers per the job/subscription target
+      const report = (w.text ?? t?.last ?? t?.buffer ?? '').trim();
+      const synthetic = binding ? (failed ? fireFailed(state, profile, binding, message, now, effects) : fireFinal(state, profile, binding, report, now, effects)) : false;
+      if (!synthetic && binding) {
+        if (failed) reply(state, profile, binding.key, `Turn failed: ${message}`, now, effects);
+        else if (text && !t?.replied) reply(state, profile, binding.key, text, now, effects);
+      }
+      const q = rt.queues[lid] ?? [];
+      if (q.length && rt.leases[lid]) {
+        const next = q.shift();
+        rt.turns[lid] = { started_at: now, buffer: '' };
+        effects.push(queuedInput(profile.name, ev.keyString, next));
+      }
+      effects.push({ type: 'save' });
+      break;
+    }
+    case 'request': {
+      if (!binding) break;
+      // Hermes's approval rule allowed it (a safe command, any other tool): it runs without asking, as under Hermes
+      if (w.hermes?.verdict === 'allow') {
+        effects.push({ type: 'respond', profile: profile.name, keyString: ev.keyString, request_id: String(w.id), response: permissionResponse(w.options, true) });
+        break;
+      }
+      // a cron fire or a webhook turn has nobody to ask: answered now (§4.2)
+      if (unattendedRequest(state, profile, binding, ev.keyString, w, now, effects)) break;
+      rt.pending_requests[String(w.id)] = { profile: profile.name, keyString: ev.keyString, runtime_id: rt.leases[lid]?.runtime_id ?? null, asked_at: now, options: w.options ?? [] };
+      const options = (w.options ?? []).map((o, i) => `${i + 1}. ${o.name}`).join('\n');
+      reply(state, profile, binding.key, `Permission needed: ${w.subject ?? 'the worker wants to act'}\nReply with a number:\n${options}`, now, effects);
+      break;
+    }
+    case 'ended':
+    case 'error': {
+      delete rt.turns[lid];
+      delete rt.starting[lid];
+      const synthetic = binding ? fireFailed(state, profile, binding, w.message ?? w.reason ?? 'worker exited', now, effects) : false;
+      if (binding) {
+        endBinding(state, profile.name, ev.keyString, 'error', now, effects);
+        if (!synthetic) reply(state, profile, binding.key, `Session ended: ${w.message ?? w.reason ?? 'worker exited'}.`, now, effects);
+      } else {
+        delete rt.leases[lid];
+      }
+      effects.push({ type: 'save' });
+      break;
+    }
+    default:
+      break;
+  }
+}
+
+/**
+ * The worker's own option for a decision nobody typed (the timeout's default,
+ * an unattended surface's policy): the first whose kind or name reads as
+ * allow/approve, or as reject/deny; `cancelled` when the worker offered neither.
+ */
+export function permissionResponse(options, allow, reason = null) {
+  const pattern = allow ? /allow|approve/i : /reject|deny/i;
+  const answer = (options ?? []).find((o) => pattern.test(o.kind ?? '') || pattern.test(o.name ?? '')) ?? null;
+  const response = answer ? (answer.response ?? answer) : { outcome: { outcome: 'cancelled' } };
+  // a denial that carries words (Claude Code's `message`) says why, so the worker can find another way
+  return !allow && reason && typeof response.message === 'string' ? { ...response, message: reason } : response;
+}
+
+/**
+ * A queued line as the worker receives it. A fire's line keeps what frames it
+ * (`context_from`, the job's `skills`) whichever flush sends it; the loop reads
+ * those from disk at send time.
+ */
+function queuedInput(profile, keyString, next) {
+  const framed = next.job_id && (next.context_from || next.skills?.length);
+  return { type: 'send_input', profile, keyString, text: next.text, ...(framed ? { context_from: next.context_from ?? null, skills: next.skills ?? [], job_id: next.job_id } : {}) };
+}
+
+/** An admin's numeric reply resolves the oldest pending request on that surface. */
+function tryResolveRequest(state, ev, effects) {
+  const rt = ensureRuntime(state);
+  const keyString = keyOf(ev);
+  const owner = profileOf(state, ev.profile);
+  const isAdmin = (owner.access.admins[ev.key.platform] ?? []).includes(ev.sender) || accessPolicy(owner, ev.key.platform) === 'open';
+  const m = /^\s*(\d+)\s*$/.exec(ev.text);
+  if (!m || !isAdmin) return false;
+  const entry = Object.entries(rt.pending_requests).find(([, p]) => p.keyString === keyString);
+  if (!entry) return false;
+  const [id, p] = entry;
+  const choice = p.options[Number(m[1]) - 1];
+  if (!choice) return false;
+  delete rt.pending_requests[id];
+  effects.push({ type: 'respond', profile: p.profile, keyString, request_id: id, response: choice.response ?? choice });
+  return true;
+}
+
+// ---------------------------------------------------------------- tick (expiry half, then §4.3's cron half)
+
+function handleTick(state, ev, effects) {
+  for (const profile of Object.values(state.profiles)) {
+    for (const [ks, b] of Object.entries(profile.bindings)) {
+      if (b.ended_at || ks.includes('#')) continue;
+      const reason = expired(b, sessionReset(profile), ev.at);
+      if (reason) endBinding(state, profile.name, ks, reason, ev.at, effects);
+    }
+  }
+  // unanswered permission requests take the worker's default (deny unless it says allow) after its timeout
+  const rt = ensureRuntime(state);
+  for (const [id, p] of Object.entries(rt.pending_requests)) {
+    const worker = state.profiles[p.profile]?.worker;
+    const timeout = worker?.permission?.timeout_seconds ?? 300;
+    if ((Date.parse(ev.at) - Date.parse(p.asked_at)) / 1000 >= timeout) {
+      delete rt.pending_requests[id];
+      effects.push({ type: 'respond', profile: p.profile, keyString: p.keyString, request_id: id, response: permissionResponse(p.options, worker?.permission?.default === 'allow') });
+    }
+  }
+  cronTick(state, ev, effects); // §4.3: due jobs, obligation retry, breakers
+}
+
+// ---------------------------------------------------------------- restart / adapter / operator
+
+// §4.7 on a clean stop: the daemon closes every runtime, so each binding that held one keeps it as the runtime to
+// resume, as a crash's pass marks it, and the next line reopens the same session. A turn cut off mid-way is told so
+// on its surface; an idle binding is not.
+function handleStopping(state, ev, effects) {
+  const rt = ensureRuntime(state);
+  for (const profile of Object.values(state.profiles)) {
+    for (const [ks, b] of Object.entries(profile.bindings)) {
+      if (b.ended_at || ks.includes('#') || !b.residue?.runtime_id) continue;
+      b.residue.resume_runtime_id = b.residue.runtime_id;
+      delete b.residue.runtime_id;
+      if (rt.turns[leaseId(profile.name, ks)] && !b.recurrence && b.key.platform !== 'webhook' && b.key.platform !== 'cron') {
+        b.residue.interrupted_at = ev.at;
+        reply(state, profile, b.key, REPLY.interrupted, ev.at, effects);
+      }
+    }
+  }
+  effects.push({ type: 'save' });
+}
+
+function handleRestart(state, ev, effects) {
+  const rt = ensureRuntime(state);
+  rt.leases = {}; rt.turns = {}; rt.queues = {}; rt.pending_requests = {};
+  let live = 0;
+  const replays = [];
+  for (const profile of Object.values(state.profiles)) {
+    // §4.7: every binding that held a lease when the daemon went away. The
+    // lease table itself is never persisted (§2.8); `residue.runtime_id`,
+    // written when the lease started, is the one fact that survived. The loop
+    // attaches where the worker's door allows it and marks the rest
+    // interrupted (`binding_interrupted` below).
+    for (const [ks, b] of Object.entries(profile.bindings)) {
+      if (b.ended_at || ks.includes('#') || !b.residue?.runtime_id) continue;
+      live += 1;
+      // a message arriving while the attach is in flight queues behind it,
+      // rather than starting a fresh runtime that would replace the session
+      ensureRuntime(state).starting[leaseId(profile.name, ks)] = true;
+      effects.push({ type: 'runtime_reattach', profile: profile.name, keyString: ks, runtime_id: b.residue.runtime_id, harness: b.worker.harness });
+    }
+    for (const o of profile.obligations) if (o.state === 'pending') replays.push({ type: 'deliver', profile: profile.name, obligation_id: o.id });
+  }
+  // every reattach runs before any replayed delivery: the loop stops an
+  // event's effects at the first that throws (a save), and a reattach left
+  // unrun would leave its surface marked starting with nothing to clear it
+  effects.push(...replays);
+  effects.push({ type: 'log', level: 'info', message: `restart at ${ev.at}: leases cleared, ${live} binding(s) to re-attach, pending obligations replayed` });
+}
+
+function handleAdapter(state, ev) {
+  const rt = ensureRuntime(state);
+  const a = rt.adapters[ev.platform] ??= { state: 'down', breaker: { failures: 0 } };
+  a.state = ev.state;
+  a.configured = ev.configured !== false;
+  if (ev.state === 'up') a.breaker = { failures: 0 };
+}
+
+/** Hermes's pairing store issued a code for a stranger: tell them, as Hermes's gateway does. */
+export function handlePairingIssued(state, ev, effects) {
+  const owner = profileOf(state, ev.profile);
+  const text = ev.code ? REPLY.notPaired(ev.code, ev.key.platform, owner.name) : REPLY.pairingBusy;
+  reply(state, owner, ev.key, text, ev.at, effects);
+}
+
+function handleOperator(state, ev, effects) {
+  const profile = profileOf(state, ev.profile);
+  switch (ev.verb) {
+    case 'pair_approve': {
+      // Hermes's pairing store holds the code (hashed); the loop asks it, and a grant comes back as `access_granted`
+      effects.push({ type: 'access_write', profile: profile.name, op: 'approve', code: ev.args.code, platforms: Object.keys(profile.channels ?? {}) });
+      break;
+    }
+    // what Hermes's store granted, mirrored into the loaded access
+    case 'access_granted': {
+      const { platform, user_id: userId } = ev.args;
+      profile.access.allowlist[platform] = [...new Set([...(profile.access.allowlist[platform] ?? []), userId])].sort();
+      break;
+    }
+    // §2.4's access verbs: the operator CLI's `pair approve`, `access
+    // allow|revoke` and `access admin add|remove` are these four events.
+    case 'access_allow':
+    case 'access_revoke':
+    case 'admin_add':
+    case 'admin_remove': {
+      const { platform, user_id: userId } = ev.args;
+      if (typeof platform !== 'string' || !platform || typeof userId !== 'string' || !userId) {
+        effects.push({ type: 'log', level: 'warn', message: `${ev.verb}: platform and user_id are required` });
+        break;
+      }
+      const list = ev.verb.startsWith('admin') ? 'admins' : 'allowlist';
+      const users = new Set(profile.access[list][platform] ?? []);
+      if (ev.verb === 'access_allow' || ev.verb === 'admin_add') users.add(userId); else users.delete(userId);
+      if (users.size) profile.access[list][platform] = [...users].sort();
+      else delete profile.access[list][platform];
+      // written where Hermes keeps it: `.env` allowlists, `config.yaml` admins (row 8)
+      effects.push({ type: 'access_write', profile: profile.name, op: ev.verb.replace('access_', ''), platform, user_id: userId });
+      break;
+    }
+    // §4.7's other half: a live binding the loop could not re-attach to. The
+    // surface is told once, in one line, on the loop's next pass.
+    case 'binding_interrupted': {
+      const rt = ensureRuntime(state);
+      const lid = leaseId(profile.name, ev.args.keyString);
+      const b = liveBinding(profile, ev.args.keyString);
+      // only the binding the attach was for: a fire or /new may have replaced it meanwhile
+      if (!b || (ev.args.runtime_id && b.residue?.runtime_id !== ev.args.runtime_id)) {
+        if (!b) delete rt.starting[lid];
+        effects.push({ type: 'log', level: 'info', message: `binding_interrupted: ${ev.args.keyString} no longer holds ${ev.args.runtime_id ?? 'that runtime'}` });
+        break;
+      }
+      b.residue.resume_runtime_id = b.residue.runtime_id;
+      delete b.residue.runtime_id;
+      b.residue.interrupted_at = ev.at;
+      // cron fires and webhook turns have no reader on their synthetic surface
+      if (!b.recurrence && b.key.platform !== 'webhook' && b.key.platform !== 'cron') {
+        reply(state, profile, b.key, REPLY.interrupted, ev.at, effects);
+      }
+      // the attach is over; what queued behind it gets a worker now (resumed where the harness can)
+      delete rt.starting[lid];
+      if (rt.queues[lid]?.length && profile.worker) startWorker(state, profile, ev.args.keyString, effects);
+      effects.push({ type: 'save' });
+      break;
+    }
+    case 'sessions_new':
+    case 'sessions_reset': {
+      const keyString = ev.args.keyString;
+      endBinding(state, profile.name, keyString, ev.verb === 'sessions_new' ? 'new' : 'reset', ev.at, effects);
+      effects.push({ type: 'save' });
+      break;
+    }
+    // Job verbs (§4.6): the same events the MCP tools, the daemon socket
+    // (ORC-13) and the operator CLI use. The caller builds a complete Job
+    // record (§2.6); the reducer only owns the state change.
+    case 'jobs_create': {
+      const job = ev.args.job;
+      if (!job || typeof job.id !== 'string' || !job.id) { effects.push({ type: 'log', level: 'warn', message: 'jobs_create: a job with an id is required' }); break; }
+      if (profile.jobs[job.id]) { effects.push({ type: 'log', level: 'warn', message: `jobs_create: job ${job.id} already exists` }); break; }
+      // a schedule nothing can evaluate would sit due on every tick (§4.3)
+      const broken = scheduleError(job.schedule) ?? modelError(profile.worker?.harness, job.model);
+      if (broken) { effects.push({ type: 'log', level: 'warn', message: `jobs_create: job ${job.id}: ${broken}` }); break; }
+      profile.jobs[job.id] = job;
+      effects.push({ type: 'save' });
+      break;
+    }
+    case 'jobs_update': {
+      const job = profile.jobs[ev.args.id];
+      if (!job) { effects.push({ type: 'log', level: 'warn', message: `jobs_update: no job ${ev.args.id}` }); break; }
+      const broken = (ev.args.patch?.schedule ? scheduleError(ev.args.patch.schedule) : null) ?? modelError(profile.worker?.harness, ev.args.patch?.model);
+      if (broken) { effects.push({ type: 'log', level: 'warn', message: `jobs_update: job ${ev.args.id}: ${broken}` }); break; }
+      Object.assign(job, ev.args.patch ?? {});
+      effects.push({ type: 'save' });
+      break;
+    }
+    case 'jobs_pause':
+    case 'jobs_resume': {
+      const job = profile.jobs[ev.args.id];
+      if (!job) { effects.push({ type: 'log', level: 'warn', message: `${ev.verb}: no job ${ev.args.id}` }); break; }
+      const broken = ev.verb === 'jobs_resume' ? scheduleError(job.schedule) : null;
+      if (broken) { effects.push({ type: 'log', level: 'warn', message: `jobs_resume: job ${ev.args.id} cannot run: ${broken}` }); break; }
+      job.enabled = ev.verb === 'jobs_resume';
+      if (job.enabled && !job.next_run_at) job.next_run_at = nextRunAt(job.schedule, ev.at, homeZone(profile));
+      effects.push({ type: 'save' });
+      break;
+    }
+    case 'jobs_run': {
+      const job = profile.jobs[ev.args.id];
+      if (!job) { effects.push({ type: 'log', level: 'warn', message: `jobs_run: no job ${ev.args.id}` }); break; }
+      job.next_run_at = ev.at; // the next tick claims it (§4.3)
+      effects.push({ type: 'save' });
+      break;
+    }
+    case 'jobs_delete': {
+      if (!profile.jobs[ev.args.id]) { effects.push({ type: 'log', level: 'warn', message: `jobs_delete: no job ${ev.args.id}` }); break; }
+      delete profile.jobs[ev.args.id];
+      effects.push({ type: 'save' });
+      break;
+    }
+    case 'send_message': {
+      const key = ev.args.key;
+      if (!key || typeof key.platform !== 'string' || typeof ev.args.text !== 'string') { effects.push({ type: 'log', level: 'warn', message: 'send_message: key and text are required' }); break; }
+      reply(state, profile, key, ev.args.text, ev.at, effects);
+      // A turn that has spoken on its own surface through the tool has said what it meant there: what is left of
+      // its text at the end is narration about that, and is not delivered a second time.
+      const own = ensureRuntime(state).turns[leaseId(profile.name, surfaceKeyString(key))];
+      if (own) own.replied = true;
+      effects.push({ type: 'save' });
+      break;
+    }
+    case 'session_handoff': {
+      const outcome = doHandoff(state, profile, ev.args.keyString, ev.args.to ?? null, ev.args.note ?? null, ev.at, effects);
+      if (!outcome.ok) effects.push({ type: 'log', level: 'warn', message: `session_handoff: ${outcome.message}` });
+      break;
+    }
+    // Profile verbs (§4.6): a profile IS a folder, so `create` adds the record
+    // and lets `save` write the folder, and `delete` removes the record and
+    // asks the loop to move the folder aside — the reducer performs no I/O and
+    // nothing here ever unlinks anything.
+    case 'profiles_create': {
+      const made = ev.args.profile;
+      if (!made || typeof made.name !== 'string' || !made.name) { effects.push({ type: 'log', level: 'warn', message: 'profiles_create: a profile record with a name is required' }); break; }
+      if (state.profiles[made.name]) { effects.push({ type: 'log', level: 'warn', message: `profiles_create: profile ${made.name} already exists` }); break; }
+      state.profiles[made.name] = made;
+      effects.push({ type: 'save' });
+      break;
+    }
+    case 'profiles_delete': {
+      const name = ev.args.name;
+      if (name === 'default') { effects.push({ type: 'log', level: 'warn', message: 'profiles_delete: the root folder IS the default profile; it is never removed' }); break; }
+      const doomed = state.profiles[name];
+      if (!doomed) { effects.push({ type: 'log', level: 'warn', message: `profiles_delete: no profile ${name}` }); break; }
+      delete state.profiles[name];
+      effects.push({ type: 'remove_profile_dir', profile: name, dir: doomed.dir });
+      effects.push({ type: 'save' });
+      break;
+    }
+    default:
+      effects.push({ type: 'log', level: 'warn', message: `unknown operator verb ${ev.verb}` });
+  }
+}
+
+// ---------------------------------------------------------------- step
+
+export function step(state, event) {
+  const effects = [];
+  switch (event.type) {
+    case 'inbound':
+      if (!tryResolveRequest(state, event, effects)) handleInbound(state, event, effects);
+      break;
+    case 'worker': handleWorker(state, event, effects); break;
+    case 'tick': handleTick(state, event, effects); break;
+    case 'hosted_result': finishHostedFire(state, event, effects); break;
+    case 'gate_result': gateResult(state, event, effects); break;
+    case 'webhook': handleWebhook(state, event, effects); break;
+    case 'restart': handleRestart(state, event, effects); break;
+    case 'stopping': handleStopping(state, event, effects); break;
+    case 'adapter': handleAdapter(state, event); break;
+    case 'operator': handleOperator(state, event, effects); break;
+    case 'pairing_issued': handlePairingIssued(state, event, effects); break;
+    default: throw new Error(`unknown event type ${event.type}`);
+  }
+  return effects;
+}
+
+export { leaseId };