Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/**
* The supervised runtime for executable Eidoverse world controllers (#7456,
* epic #7453) — the install store, the tick pass, and the arming reconcile.
*
* `lib/eidoverseControllers.js` owns the schema and the sandboxed step
* boundary; `eidoverseControllerRegistry.js` owns the fixed id-to-code map.
* This module is the persistence, the clock, and the supervision around them,
* so that a controller a mind installed keeps running between that mind's
* wakes and across a server restart — SwarmWorld's "executable inheritance",
* which is the whole point of the issue.
*
* **The tick path cannot reach an AI provider.** A controller step is
* synchronous (`runControllerStep` refuses a Promise), so there is no await
* for a provider call to hide behind, and the only thing a tick may do
* outwards is deliver effects from a closed vocabulary through the existing
* Eidoverse world verbs, which make no provider call either. That is root
* AGENTS.md's "no cold-bootstrap LLM calls" rule enforced structurally rather
* than trusted — boot arms timers here and nothing else.
*
* **Arming is reconciled at every gate move, not only at boot.** Installing,
* retiring, or disarming a controller all end in
* `reconcileEidoverseControllerTicks()`, which registers the supervisor
* schedule when at least one install is armed and cancels it when none is.
* `services/beeperArming.js` is the worked example of the same contract; the
* failure it exists to prevent is background work whose gate moved while the
* work kept running (or never started) until the next restart.
*
* **A pass never replays a backlog.** Every due install steps exactly once per
* pass and its next tick is measured from now — see `nextControllerTickAt`. A
* laptop asleep for three days wakes to one tick, not to eight hundred
* ambient verbs it owes the world.
*
* Storage is `data/eidoverse/controllers.json` — `file-primary` and MACHINE
* LOCAL, the same class as `foundations.json` and `portos-world.json` beside
* it (`docs/STORAGE.md`). None of it federates: a controller install names
* this install's world entities and carries its author's intent, and the
* machine-local privacy ADR keeps records off the federation layer. There is
* no `data.reference/` seed — an absent file IS the empty set every install
* starts from. Migration 425 adds unknown completed-delivery history to older stores.
*/
import { join } from 'node:path';
import { randomUUID } from 'node:crypto';
import { PATHS, atomicWrite, readJSONFile } from '../lib/fileUtils.js';
import { createMutex } from '../lib/asyncMutex.js';
import {
EIDOVERSE_CONTROLLER_LIMITS,
controllerTickDue,
eidoverseControllerInstallSchema,
eidoverseRiddleActionSchema,
nextControllerTickAt,
runControllerStep,
summarizeControllerEffect,
summarizeControllerInstall,
} from '../lib/eidoverseControllers.js';
import { findControllerDefinitionById } from './eidoverseControllerRegistry.js';
import { cancel, getEvent, schedule } from './eventScheduler.js';
/** Storage-layout version stamped on `data/eidoverse/controllers.json`. */
const STORE_SCHEMA_VERSION = 2;
const SCHEDULER_EVENT_ID = 'eidoverse-controller-tick';
/**
* How often the supervisor wakes. This is NOT a controller's cadence — each
* install carries its own `tickIntervalMs` and steps only when due — it is the
* resolution at which "due" is noticed.
*
* Derived from the cadence floor rather than written beside it, because the two
* numbers are one decision: a `tickIntervalMs` below the supervisor's wake
* interval is a cadence the schema would accept and the supervisor could never
* honor, and two independent constants would drift into exactly that.
*/
const SUPERVISOR_INTERVAL_MS = EIDOVERSE_CONTROLLER_LIMITS.minTickIntervalMs;
const LOG_PREFIX = '🌀 Eidoverse controllers';
// Read through `PATHS` per call, NOT `dataPath()`: a suite redirects the data
// root by proxying this module's `fileUtils` import, and `dataPath()` resolves
// against `paths.js`'s own `PATHS` binding, which that proxy never sees — so
// the helper would send every test at the live install's controllers.
const storeFile = () => join(PATHS.data, 'eidoverse', 'controllers.json');
const withStoreLock = createMutex();
// Keep explicit round messages ordered without holding the shared store lock
// across world I/O. Ordinary controller management remains available.
const withRiddleActionLock = createMutex();
/**
* Serializes whole tick passes. A pass reads every install, steps the due
* ones, and writes them back; two overlapping passes (the scheduler firing
* while a reconcile-triggered pass is still running) would each write a record
* the other had already advanced. This is the single-writer re-entrancy guard
* root AGENTS.md sanctions, not a defence against competing humans.
*/
let passTail = Promise.resolve();
/**
* Strict read: a `controllers.json` this process cannot parse must NOT read as
* "nothing installed", because the very next write would then replace the
* user's armed controllers with an empty set. `strict: true` throws on
* unreadable bytes, while a genuinely ABSENT file still reads as the empty set
* it is.
*
* Returns the file's OWN stamped `schemaVersion` alongside the installs, not
* the build's constant — a store written by a newer install must keep
* reporting what it actually is (#7629). An absent file, or one predating the
* stamp, reads as this build's version: there is nothing to disagree with yet.
*/
async function readInstalls() {
const raw = await readJSONFile(storeFile(), null, { allowArray: false, strict: true });
const installs = raw && typeof raw === 'object' && raw.installs && typeof raw.installs === 'object' ? { ...raw.installs } : {};
const schemaVersion = raw && typeof raw === 'object' && Number.isInteger(raw.schemaVersion) ? raw.schemaVersion : STORE_SCHEMA_VERSION;
// Additive read compatibility even before the offline migration has run.
// Never derive acknowledgements from old outcomes or proposal summaries.
if (schemaVersion <= STORE_SCHEMA_VERSION) {
for (const [id, record] of Object.entries(installs)) {
installs[id] = { lastCompletedDelivery: null, ...record };
}
}
return { schemaVersion, installs };
}
/**
* Writes never DOWNGRADE the file's stamp (#7629). A store a newer build wrote
* carries a higher `schemaVersion`, and this build still has to persist to it —
* a disarm, a delivery outcome. Re-stamping it with this build's own older
* constant would erase the very signal `stepInstall` refuses to step on, so the
* newer-store guard would fire exactly once and then never again, and the
* newer build would read its own file back as one this version wrote. Callers
* pass the stamp they read under the same lock.
*/
async function writeInstalls(installs, storeSchemaVersion = STORE_SCHEMA_VERSION) {
const schemaVersion = Math.max(STORE_SCHEMA_VERSION, storeSchemaVersion);
await atomicWrite(storeFile(), { schemaVersion, installs });
}
/** Every controller this install has, most recently installed first. */
export async function listEidoverseControllers() {
const { schemaVersion, installs: stored } = await readInstalls();
const installs = Object.values(stored)
.sort((a, b) => String(b.installedAt || '').localeCompare(String(a.installedAt || '')));
const counts = installs.reduce((totals, entry) => ({
total: totals.total + 1,
armed: totals.armed + (entry.armed === true ? 1 : 0),
delivering: totals.delivering + (entry.armed === true && entry.deliverEffects === true ? 1 : 0),
}), { total: 0, armed: 0, delivering: 0 });
return { schemaVersion, counts, installs };
}
export async function getEidoverseControllerInstall(id) {
const { installs } = await readInstalls();
return installs[id] || null;
}
const refused = (reasons) => ({ outcome: 'refused', install: null, reasons });
/**
* Install (or re-install) a controller.
*
* A refusal is a RESULT, not an exception: "that controller id is not one this
* version ships" and "that config is not one this controller accepts" are
* ordinary, expected output the caller shows the author with its reasons —
* the same proposal-versus-consequence shape the construction tools and the
* promote gate already have.
*
* Re-installing an existing id keeps its `installedAt` and its accumulated
* `tick` ordinal but REBUILDS state from the new config. State is shaped by
* the config that produced it; carrying it across an edit would leave a
* controller reasoning over counters that describe a configuration nobody has.
* The first tick is one full interval away, never immediate: installing arms a
* schedule, it does not fire a world verb.
*
* `resolveDefinition` is injectable so a test can install a controller of its
* own shaping without a registry back door. It is a function argument inside
* the server process, never anything a request body can reach — the id-only
* rule the registry enforces is not weakened by it.
*/
export async function installEidoverseController(input, {
installedBy = 'user',
now = new Date().toISOString(),
resolveDefinition = findControllerDefinitionById,
derivedFrom = null,
} = {}) {
const parsed = eidoverseControllerInstallSchema.safeParse(input);
if (!parsed.success) return refused(parsed.error.issues.map((issue) => `${issue.path.join('.') || 'input'}: ${issue.message}`));
const authored = parsed.data;
const definition = await resolveDefinition(authored.controllerId);
if (!definition) return refused([`no controller is registered under "${authored.controllerId}" — a controller is named by id, never by a module path, so only the ids this install ships can be installed`]);
const config = definition.configSchema.safeParse(authored.config);
if (!config.success) return refused(config.error.issues.map((issue) => `config.${issue.path.join('.') || '<root>'}: ${issue.message}`));
// `armed` DEFAULTS to true in the schema, so an absent flag is indistinguishable
// from `armed: true` by the time zod is done with it. On a re-install that
// difference decides whether a controller somebody deliberately quieted comes
// back on by itself, so the raw input is what answers it — the "absent vs
// intentionally empty" rule in AGENTS.md, applied to a boolean.
const armedRequested = typeof input?.armed === 'boolean' ? input.armed : null;
const nowMs = Date.parse(now);
return withStoreLock(async () => {
const { schemaVersion: storeSchemaVersion, installs } = await readInstalls();
const existing = installs[authored.id] || null;
if (!existing && Object.keys(installs).length >= EIDOVERSE_CONTROLLER_LIMITS.installs) {
return refused([`this install already holds ${EIDOVERSE_CONTROLLER_LIMITS.installs} controllers — retire one before installing another`]);
}
const armed = armedRequested ?? (existing ? existing.armed : authored.armed);
const record = {
...authored,
armed,
config: config.data,
installedBy: existing?.installedBy || installedBy,
installedAt: existing?.installedAt || now,
updatedAt: now,
state: definition.createState(config.data),
tick: existing?.tick ?? 0,
nextTickAt: nextControllerTickAt(authored, nowMs),
lastTickAt: existing?.lastTickAt ?? null,
lastOutcome: null,
lastCompletedDelivery: null,
recentEffects: [],
consecutiveFailures: 0,
consecutiveDeliveryFailures: 0,
// A re-install that leaves a controller disarmed keeps the reason it was
// disarmed for, so the author is not left looking at a stopped controller
// with no explanation. Re-arming answers the reason, so it clears it.
disarmedReason: armed ? null : (existing?.disarmedReason ?? null),
// Attribution outlives a re-install, the same way `installedBy` and
// `installedAt` do (#7626). An adopted controller that somebody later
// re-installs by hand — to change its cadence, to re-arm it — is still
// the peer's contribution standing in this world, and an edge that
// vanished on the first ordinary edit would make erasing provenance the
// path of least effort all over again. A fresh `derivedFrom` (a
// re-adopt) wins over the stored one; an ordinary install passes none
// and inherits whatever the record already carried.
derivedFrom: derivedFrom ?? existing?.derivedFrom ?? null,
};
installs[authored.id] = record;
await writeInstalls(installs, storeSchemaVersion);
console.log(`${LOG_PREFIX}: installed "${record.id}" (${record.controllerId}, every ${Math.round(record.tickIntervalMs / 1000)}s, ${record.armed ? 'armed' : 'disarmed'})`);
return { outcome: 'installed', install: record, reasons: [] };
}).then(afterGateMove('install'));
}
/**
* Retire a controller — remove it and stop it stepping.
*
* Retiring DELETES the install rather than parking it. A controller that is
* "installed but off forever" is a record nobody reads and a counter that
* silently drifts from the world it describes; an author who wants it back
* installs it again, which is one tool call.
*/
export async function retireEidoverseController(id) {
return withStoreLock(async () => {
const { schemaVersion: storeSchemaVersion, installs } = await readInstalls();
const existing = installs[id];
if (!existing) return { outcome: 'unknown-install', install: null, reasons: [`no controller is installed under "${id}"`] };
delete installs[id];
await writeInstalls(installs, storeSchemaVersion);
console.log(`${LOG_PREFIX}: retired "${id}" (${existing.controllerId}) after ${existing.tick} tick${existing.tick === 1 ? '' : 's'}`);
return { outcome: 'retired', install: existing, reasons: [] };
}).then(afterGateMove('retire'));
}
/**
* Arm or disarm an installed controller without losing its state.
*
* The state survives the pause on purpose: a controller the author quiets for
* an afternoon should resume its count, not restart it. Explicitly clears any
* `disarmedReason` the supervisor set, since a human re-arming has answered it.
*/
export async function setEidoverseControllerArmed(id, armed, { now = new Date().toISOString() } = {}) {
const nowMs = Date.parse(now);
return withStoreLock(async () => {
const { schemaVersion: storeSchemaVersion, installs } = await readInstalls();
const existing = installs[id];
if (!existing) return { outcome: 'unknown-install', install: null, reasons: [`no controller is installed under "${id}"`] };
const record = {
...existing,
armed: armed === true,
updatedAt: now,
// Re-arming restarts the cadence from now rather than firing immediately
// on the next pass against a `nextTickAt` that went stale while paused.
...(armed === true ? {
nextTickAt: nextControllerTickAt(existing, nowMs),
consecutiveFailures: 0,
consecutiveDeliveryFailures: 0,
disarmedReason: null,
} : {}),
};
installs[id] = record;
await writeInstalls(installs, storeSchemaVersion);
return { outcome: 'updated', install: record, reasons: [] };
}).then(afterGateMove('arm-toggle'));
}
/**
* Change an installed controller's `config` while its accumulated `state`
* survives untouched (#7629) — the "inherit and modify" verb the epic names.
* A re-install of the same id is the alternative, but it REBUILDS state from
* scratch (`installEidoverseController` above); a later mind that only wants
* to tune a value should not have to destroy what the controller has already
* accumulated to do it.
*
* Re-parsed through the definition's own `configSchema`, the same refusal
* shape every other install-touching call uses: a config the schema rejects
* changes nothing and reports why, rather than throwing.
*/
export async function updateEidoverseControllerConfig(id, config, {
now = new Date().toISOString(),
resolveDefinition = findControllerDefinitionById,
} = {}) {
return withStoreLock(async () => {
const { schemaVersion: storeSchemaVersion, installs } = await readInstalls();
const existing = installs[id];
if (!existing) return { outcome: 'unknown-install', install: null, reasons: [`no controller is installed under "${id}"`] };
const definition = await resolveDefinition(existing.controllerId);
if (!definition) return refused([`no controller is registered under "${existing.controllerId}" any more — this install was authored by a version that shipped it`]);
const parsed = definition.configSchema.safeParse(config);
if (!parsed.success) return refused(parsed.error.issues.map((issue) => `config.${issue.path.join('.') || '<root>'}: ${issue.message}`));
const record = { ...existing, config: parsed.data, updatedAt: now };
installs[id] = record;
await writeInstalls(installs, storeSchemaVersion);
console.log(`${LOG_PREFIX}: updated config for "${id}" (${existing.controllerId}), state preserved`);
return { outcome: 'updated', install: record, reasons: [] };
});
}
/**
* Every path that moves the arming gate ends here, so no caller has to
* remember to reconcile — the failure mode root AGENTS.md names is a toggle
* that arms background work and only reconciles it at the next boot.
*/
const afterGateMove = (reason) => async (result) => {
await reconcileEidoverseControllerTicks({ reason });
return result;
};
/** Apply one explicit action to a shipped riddle-ledger install. Local progress
* is persisted BEFORE delivery, so a restart never repeats a guess or a say.
* `delivery` is a separate verdict; pending after a crash is unknown, not an
* acknowledgement. Neither this path nor quiet ticks retry outbound work.
*/
export async function interactEidoverseRiddleLedger(input, {
now = new Date().toISOString(),
signal,
deliver = deliverControllerEffects,
} = {}) {
const parsed = eidoverseRiddleActionSchema.safeParse(input);
if (!parsed.success) return refused(parsed.error.issues.map((issue) => `${issue.path.join('.') || 'input'}: ${issue.message}`));
const action = parsed.data;
return withRiddleActionLock(async () => {
signal?.throwIfAborted();
const applied = await withStoreLock(async () => {
const { schemaVersion, installs } = await readInstalls();
if (schemaVersion > STORE_SCHEMA_VERSION) return refused(['Controller store is from a newer build; upgrade before interacting.']);
const record = installs[action.id];
if (!record) return { outcome: 'unknown-install', install: null, reasons: ['Install a riddle-ledger controller explicitly first.'] };
if (record.controllerId !== 'riddle-ledger') return refused(['This action only supports the shipped riddle-ledger controller.']);
if (!record.armed) return refused(['This controller is disarmed; arm it explicitly before interacting.']);
const definition = await findControllerDefinitionById('riddle-ledger');
if (!definition) return refused(['This build does not ship the riddle-ledger controller.']);
const config = definition.configSchema.safeParse(record.config);
if (!config.success) return refused(['Stored riddle config is incompatible; no action was applied.']);
const proposed = definition.interact(record.state, action);
if (proposed.refused) return refused([proposed.refused]);
const operationId = randomUUID();
const delivery = { status: record.deliverEffects ? 'pending' : 'disabled', delivered: 0, reason: null };
const outcome = runControllerStep({
definition: { ...definition, step: () => ({ ...proposed, state: { ...proposed.state, operationId, delivery } }) },
state: record.state, config: config.data, tick: record.tick,
});
if (!outcome.ok) return refused([outcome.reason]);
const install = { ...record, state: outcome.state, updatedAt: now };
installs[action.id] = install;
await writeInstalls(installs, schemaVersion);
return { outcome: 'applied', install, reasons: [], effects: outcome.effects };
});
if (applied.outcome !== 'applied') return applied;
const { effects, ...result } = applied;
if (!result.install.deliverEffects) return { ...result, delivery: result.install.state.delivery };
const attempt = await deliver(effects, { signal }).catch((error) => ({ delivered: 0, error: String(error?.message ?? error) || 'World delivery failed.' }));
const acknowledged = attempt.delivered === 1 && !attempt.error;
const delivery = {
status: acknowledged ? 'acknowledged' : 'refused',
delivered: attempt.delivered,
reason: acknowledged ? null : String(attempt.error || 'No world acknowledgement was recorded.').slice(0, EIDOVERSE_CONTROLLER_LIMITS.reasonMax),
};
return withStoreLock(async () => {
const { schemaVersion, installs } = await readInstalls();
const current = installs[action.id];
// A management operation may replace/retire the install during delivery.
// A fresh server-generated id prevents stamping its receipt over a reset.
if (current?.state?.operationId !== result.install.state.operationId) {
return { outcome: 'superseded', install: null, delivery, reasons: ['The install changed during delivery; this receipt was not attached to the replacement.'] };
}
const install = { ...current, state: { ...current.state, delivery } };
installs[action.id] = install;
await writeInstalls(installs, schemaVersion);
return { ...result, install, delivery };
});
});
}
// ---------------------------------------------------------------------------
// The tick pass
// ---------------------------------------------------------------------------
/**
* Deliver one controller's effects into the world.
*
* Lazily imported: `eidoverseWorld.js` carries the world socket, the
* projection planner and the design resolver, and only an install that
* explicitly turned `deliverEffects` on ever reaches them — a static import
* would put that whole subtree in the closure of everything that merely lists
* controllers. Neither verb calls an AI provider.
*
* `augmentEidoverseWorld()` never throws on a world refusal (#7454) — the
* verdict is its RETURN VALUE (`success`, `applied`, per-operation
* `outcome`), so it must be read, not assumed delivered because the await
* resolved. #7628 was exactly this: the return value was discarded, so a
* controller whose every write the world refused counted as delivered every
* tick, forever. `delivered` here is the world's own committed count
* (`applied`), never the loop's attempt count, and a `rewritten` operation
* counts as delivered — the world landed different args, not nothing — only
* `refused` does not.
*
* @returns {Promise<{ delivered: number, error: string|null }>}
*/
async function deliverControllerEffects(effects, { signal } = {}) {
const outbound = effects.filter((effect) => effect.kind !== 'note');
if (outbound.length === 0) return { delivered: 0, error: null };
const world = await import('./eidoverseWorld.js');
let delivered = 0;
let error = null;
for (const effect of outbound) {
try {
if (effect.kind === 'say') {
// A resolved say is acknowledged; preserve that count if a later
// effect throws, rather than losing already-committed world work.
await world.sayInEidoverseWorld(effect.text, { signal });
delivered += 1;
continue;
}
const result = await world.augmentEidoverseWorld(effect.operations, { signal });
delivered += result.applied;
if (result.success === false && error === null) {
const refusal = result.operations.find((operation) => operation.outcome === 'refused');
error = refusal?.reason ?? 'Eidoverse refused part of this augment batch.';
}
} catch (failure) {
return { delivered, error: String(failure?.message ?? failure) || 'World delivery failed.' };
}
}
return { delivered, error };
}
function recordedEffects(existing, effects, { at, tick }) {
const added = effects.map((effect) => ({ at, tick, kind: effect.kind, summary: summarizeControllerEffect(effect) }));
return [...added, ...existing].slice(0, EIDOVERSE_CONTROLLER_LIMITS.recentEffects);
}
/**
* An immediate disarm that does NOT consume a tick — the shape a controller
* id that no longer resolves, a store from a build this one cannot read, or a
* config that no longer parses all share: none of these is a transient
* failure retrying could recover from, so none should count as an attempt or
* wait out `maxConsecutiveFailures` before saying so.
*/
function disarmedWithoutStepping(record, { reason, nextTickAt, at }) {
console.error(`❌ ${LOG_PREFIX}: disarming "${record.id}" — ${reason}`);
return {
record: {
...record, armed: false, disarmedReason: reason, nextTickAt, lastTickAt: at,
lastOutcome: { at, tick: record.tick, ok: false, reason, effects: 0, delivered: 0, deliveryError: null },
},
effects: [],
};
}
/**
* Advance one install by one tick and return the record to persist.
*
* A failure disarms after `maxConsecutiveFailures` in a row rather than
* retrying forever: a controller failing every minute writes a log nobody
* reads, and one that stopped and says why is a thing the author can fix. A
* controller id that no longer resolves disarms immediately — retrying a
* missing definition cannot start succeeding.
*
* Two more disarm-immediately cases (#7629), both because retrying cannot
* help: `storeSchemaVersion` ahead of this build's own `STORE_SCHEMA_VERSION`
* means a newer install (or a not-yet-upgraded restore) wrote this file, so
* stepping it here would run this build's older rules against a shape it does
* not fully understand; and `record.config` re-parsed against the
* definition's OWN `configSchema` catches a config that stopped validating
* since install (a shipped schema tightened, a hand-edited file) before it
* ever reaches `step()`. A parse that succeeds but changes the value — a
* newly-added default landing for the first time — is persisted back onto the
* record here, so the default applies exactly once rather than being
* re-derived on every tick.
*/
async function stepInstall(record, { nowMs, at, resolveDefinition, storeSchemaVersion }) {
const nextTickAt = nextControllerTickAt(record, nowMs);
if (storeSchemaVersion > STORE_SCHEMA_VERSION) {
const reason = `controllers.json is stamped schemaVersion ${storeSchemaVersion}, newer than this build's ${STORE_SCHEMA_VERSION} — refusing to step until this build is upgraded`;
return disarmedWithoutStepping(record, { reason, nextTickAt, at });
}
const definition = await resolveDefinition(record.controllerId);
if (!definition) {
const reason = `no controller is registered under "${record.controllerId}" any more — this install was authored by a version that shipped it`;
return disarmedWithoutStepping(record, { reason, nextTickAt, at });
}
const reparsedConfig = definition.configSchema.safeParse(record.config);
if (!reparsedConfig.success) {
const reason = `stored config no longer parses against "${record.controllerId}"'s schema: ${reparsedConfig.error.issues.map((issue) => `${issue.path.join('.') || '<root>'}: ${issue.message}`).join('; ')}`.slice(0, EIDOVERSE_CONTROLLER_LIMITS.reasonMax);
return disarmedWithoutStepping(record, { reason, nextTickAt, at });
}
const config = reparsedConfig.data;
const tick = record.tick + 1;
const outcome = runControllerStep({ definition, state: record.state, config, tick });
if (!outcome.ok) {
const consecutiveFailures = record.consecutiveFailures + 1;
const exhausted = consecutiveFailures >= EIDOVERSE_CONTROLLER_LIMITS.maxConsecutiveFailures;
console.error(`❌ ${LOG_PREFIX}: "${record.id}" tick ${tick} failed (${consecutiveFailures}/${EIDOVERSE_CONTROLLER_LIMITS.maxConsecutiveFailures}): ${outcome.reason}`);
return {
record: {
...record,
config,
// The tick ordinal advances on a failure too: it counts attempts the
// supervisor made, so a controller cannot look younger than it is by
// failing, and a step that reads `tick` sees time moving either way.
tick,
consecutiveFailures,
...(exhausted ? { armed: false, disarmedReason: `disarmed after ${consecutiveFailures} consecutive failed ticks: ${outcome.reason}` } : {}),
nextTickAt,
lastTickAt: at,
lastOutcome: { at, tick, ok: false, reason: outcome.reason, effects: 0, delivered: 0, deliveryError: null },
},
effects: [],
};
}
return {
record: {
...record,
config,
state: outcome.state,
tick,
consecutiveFailures: 0,
nextTickAt,
lastTickAt: at,
// Delivery has not run yet — it happens after the store lock is released.
// A reader between the two phases sees an honest "nothing delivered yet"
// rather than a number the pass has not earned.
lastOutcome: { at, tick, ok: true, reason: null, effects: outcome.effects.length, delivered: 0, deliveryError: null },
recentEffects: recordedEffects(record.recentEffects, outcome.effects, { at, tick }),
},
effects: record.deliverEffects ? outcome.effects : [],
};
}
/**
* Deliver one pass's effects, OUTSIDE the store lock.
*
* Stepping is synchronous and fast; reaching the world is neither. Holding the
* store lock across a world call would block a mind's install or retire for as
* long as an unreachable world takes to give up — so the pass steps and writes
* first, then delivers, then records what happened in a second short write.
*
* try/catch per install at a boundary OUTSIDE the Express request lifecycle,
* per the explicit exception in AGENTS.md "Code Conventions": the world may be
* unreachable, and a rejection here would surface from a timer callback. A
* failed delivery is recorded and the STEP still counts — the controller's own
* state already advanced, and re-running it to retry a world write would
* double-count everything it did.
*/
async function deliverPassEffects(stepped, { deliver, signal }) {
const deliveries = [];
for (const { record, effects } of stepped) {
const outbound = effects.filter((effect) => effect.kind === 'say' || effect.kind === 'augment');
if (outbound.length === 0) continue;
const at = record.lastOutcome.at;
try {
const { delivered, error } = await deliver(outbound, { signal });
const reason = error == null ? null : (String(error).trim() || 'World delivery failed.').slice(0, EIDOVERSE_CONTROLLER_LIMITS.reasonMax);
deliveries.push({ id: record.id, at, tick: record.tick, delivered, error: reason });
} catch (error) {
const message = (String(error?.message ?? error).trim() || 'World delivery failed.').slice(0, EIDOVERSE_CONTROLLER_LIMITS.reasonMax);
console.error(`❌ ${LOG_PREFIX}: "${record.id}" tick ${record.tick} stepped but could not reach the world: ${message}`);
deliveries.push({ id: record.id, at, tick: record.tick, delivered: 0, error: message });
}
}
return deliveries;
}
/**
* Fold delivery outcomes back onto the records they belong to.
*
* Each patch is applied only while the record's `lastOutcome.tick` and `at`
* still match the tick that produced those effects: an install or retire landing
* between the two phases has replaced what the delivery was about, and
* stamping a delivery count onto it would describe work that record never did.
*
* A run of REFUSED deliveries disarms the same way a run of throwing/refusing
* `step()`s already does (#7628): `consecutiveFailures` only counts the step,
* so a controller that steps cleanly every tick while the world refuses
* everything it proposes would otherwise never disarm and never report
* anything but "ok". `consecutiveDeliveryFailures` is that same clause, keyed
* on the delivery verdict instead.
*
* @returns {Promise<{ gateMoved: boolean }>}
*/
async function recordDeliveries(deliveries) {
if (deliveries.length === 0) return { gateMoved: false };
return withStoreLock(async () => {
const { schemaVersion: storeSchemaVersion, installs } = await readInstalls();
let changed = false;
let gateMoved = false;
for (const { id, at, tick, delivered, error } of deliveries) {
const current = installs[id];
if (!current || current.lastOutcome?.tick !== tick || current.lastOutcome.at !== at) continue;
const consecutiveDeliveryFailures = error ? (current.consecutiveDeliveryFailures ?? 0) + 1 : 0;
const exhausted = error && consecutiveDeliveryFailures >= EIDOVERSE_CONTROLLER_LIMITS.maxConsecutiveFailures;
if (exhausted) {
console.error(`❌ ${LOG_PREFIX}: disarming "${id}" — ${consecutiveDeliveryFailures} consecutive delivery failures: ${error}`);
}
installs[id] = {
...current,
lastOutcome: { ...current.lastOutcome, delivered, deliveryError: error },
lastCompletedDelivery: { at, tick, ok: !error, delivered, reason: error },
consecutiveDeliveryFailures,
...(exhausted ? {
armed: false,
disarmedReason: `disarmed after ${consecutiveDeliveryFailures} consecutive delivery failures: ${error}`,
} : {}),
};
changed = true;
gateMoved = gateMoved || exhausted;
}
if (changed) await writeInstalls(installs, storeSchemaVersion);
return { gateMoved };
});
}
/**
* Run one supervisor pass: step every armed install that is due.
*
* Three phases, and the split is the point. The step phase holds the store
* lock — read, step every due install, write — because stepping is synchronous
* and fast and nothing else may interleave a write with it. Delivery then runs
* with the lock RELEASED, because reaching the world is neither fast nor
* bounded by anything this module controls, and a mind's install call must not
* queue behind an unreachable world. A short third phase folds the delivery
* outcomes back on.
*
* Passes are serialized against each other on `passTail`, so the gap between
* phases can only be filled by an install/retire/arm — which the third phase's
* tick-match guard already refuses to stamp over.
*
* @returns {Promise<{ ticked: number, due: number, results: Array }>}
*/
export function tickEidoverseControllers(options = {}) {
const run = () => tickOnce(options);
const next = passTail.then(run, run);
passTail = next.then(() => {}, () => {});
return next;
}
async function tickOnce({
now = new Date().toISOString(),
resolveDefinition = findControllerDefinitionById,
deliver = deliverControllerEffects,
signal,
} = {}) {
const nowMs = Date.parse(now);
const pass = await withStoreLock(async () => {
const { schemaVersion: storeSchemaVersion, installs } = await readInstalls();
const due = Object.values(installs).filter((record) => controllerTickDue(record, nowMs));
if (due.length === 0) return { ticked: 0, due: 0, results: [], stepped: [], gateMoved: false };
const stepped = [];
let gateMoved = false;
for (const record of due) {
const next = await stepInstall(record, { nowMs, at: now, resolveDefinition, storeSchemaVersion });
installs[next.record.id] = next.record;
gateMoved = gateMoved || next.record.armed !== record.armed;
stepped.push(next);
}
await writeInstalls(installs, storeSchemaVersion);
return {
ticked: stepped.length,
due: due.length,
results: stepped.map(({ record }) => ({ id: record.id, tick: record.tick, ok: record.lastOutcome?.ok === true, reason: record.lastOutcome?.reason ?? null })),
stepped,
gateMoved,
};
});
const { gateMoved: deliveryGateMoved } = await recordDeliveries(await deliverPassEffects(pass.stepped, { deliver, signal }));
// A pass that disarmed a controller — whether stepping it failed or, per
// #7628, delivering its effects into the world did — has moved the arming
// gate, so it reconciles for the same reason install and retire do. The
// reconcile is idempotent and re-reads the gate itself, so it correctly
// does nothing when other installs are still armed and stands the
// supervisor down when the disarmed one was the last.
if (pass.gateMoved || deliveryGateMoved) await reconcileEidoverseControllerTicks({ reason: 'supervisor-disarm' });
const { stepped: _stepped, gateMoved: _gateMoved, ...result } = pass;
return result;
}
// ---------------------------------------------------------------------------
// Arming
// ---------------------------------------------------------------------------
let reconcileTail = Promise.resolve();
/**
* Bring the supervisor schedule into line with whether anything is armed.
*
* IDEMPOTENT and safe to call repeatedly — a reconcile that finds the schedule
* already registered leaves it alone rather than re-`schedule()`ing it, which
* would reset `nextRunAt` a whole interval into the future every time an
* author touched an unrelated install. Logging is transition-only, so an
* install with no controllers reconciles silently, boot included.
*
* @returns {Promise<{armed: boolean, scheduled: boolean, changed: boolean}>}
*/
export function reconcileEidoverseControllerTicks({ reason = 'unspecified' } = {}) {
const run = () => reconcileOnce(reason);
const next = reconcileTail.then(run, run);
reconcileTail = next.then(() => {}, () => {});
return next;
}
async function reconcileOnce(reason) {
const { installs } = await readInstalls();
const armed = Object.values(installs).some((record) => record.armed === true);
const registered = Boolean(getEvent(SCHEDULER_EVENT_ID));
if (!armed) {
const changed = registered ? Boolean(cancel(SCHEDULER_EVENT_ID)) : false;
if (changed) console.log(`${LOG_PREFIX}: disarmed (${reason})`);
return { armed: false, scheduled: false, changed };
}
if (registered) return { armed: true, scheduled: true, changed: false };
schedule({
id: SCHEDULER_EVENT_ID,
type: 'interval',
intervalMs: SUPERVISOR_INTERVAL_MS,
handler: supervisorPass,
metadata: { source: 'eidoverseControllerRuntime' },
});
console.log(`${LOG_PREFIX}: armed (${reason})`);
return { armed: true, scheduled: true, changed: true };
}
/**
* The scheduled handler. `eventScheduler.runEvent` already records and re-arms
* around a rejection, but this runs outside the Express request lifecycle, so
* it carries its own try/catch and emoji log per AGENTS.md rather than relying
* on a caller two modules away to keep doing so.
*/
async function supervisorPass() {
try {
return await tickEidoverseControllers();
} catch (error) {
console.error(`❌ ${LOG_PREFIX}: tick pass failed: ${error.message}`);
return { ticked: 0, due: 0, results: [] };
}
}
/** Whether the supervisor schedule is currently registered. */
export function isEidoverseControllerSupervisorRegistered() {
return Boolean(getEvent(SCHEDULER_EVENT_ID));
}
/**
* Arm the supervisor at boot, so controllers survive a restart — the
* "executable inheritance" half of the issue. Boot only ARMS a timer: nothing
* steps until an install's own cadence elapses, and no provider is reachable
* from the tick path at all.
*/
export async function startEidoverseControllerSupervisor() {
return reconcileEidoverseControllerTicks({ reason: 'boot' });
}
/** Cancel the supervisor schedule and forget the serialization tails. */
export function __resetEidoverseControllerRuntimeForTests() {
cancel(SCHEDULER_EVENT_ID);
passTail = Promise.resolve();
reconcileTail = Promise.resolve();
}
// Re-exported so a caller that already has the runtime does not need a second
// import to shape a record for a prompt or a UI.
export { summarizeControllerInstall };