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
/**
* Regression guard for the agent-lifecycle circular-dependency cluster (#2837).
*
* The cluster — agentLifecycle / agentCliSpawning / agentTuiSpawning /
* agentManagement / subAgentSpawner / cosAgentLifecycle — used to contain two real
* STATIC cycles plus three `await import(...)` workarounds whose only job was to
* dodge the load-time cycle. Both were fixed by extracting the shared pieces
* (finalize, summary extraction, runner sync, runner output batchers) into leaf
* modules that nothing in the cluster is imported BY.
*
* This test re-derives the static import graph of `server/services` from source
* and asserts the cluster is acyclic. It scans STATIC imports/re-exports only —
* `await import()` is deferred to call time and therefore harmless for module
* initialization order; a static cycle is what produces TDZ/undefined-binding
* failures at boot.
*/
import { describe, it, expect } from 'vitest';
import { readFileSync } from 'fs';
import { fileURLToPath } from 'url';
import { dirname, join, relative, resolve } from 'path';
import { buildStaticImportGraph, findImportCycles } from '../lib/staticImportGraph.js';
const SERVICES_DIR = dirname(fileURLToPath(import.meta.url));
// The modules the #2837 audit named, plus the leaf modules extracted to break
// the cycle. A cycle anywhere in `server/services` will be reported, but only a
// cycle TOUCHING one of these fails the assertion — unrelated pre-existing
// cycles elsewhere are out of scope for this guard.
const CLUSTER = [
'agentLifecycle.js',
'agentCliSpawning.js',
'agentTuiSpawning.js',
'agentManagement.js',
'subAgentSpawner.js',
'cosAgentLifecycle.js',
'agentFinalization.js',
'agentRunFinalize.js',
'agentSummaryExtraction.js',
'agentRunnerSync.js',
'agentRunnerOutputBatchers.js',
'agentOrchestrator.js',
];
// The static-import scan, the services-directory graph build and the cycle walk
// all live in `server/lib/staticImportGraph.js` so this guard and the
// identity/digital-twin one (`twinImportCycles.test.js`) share ONE parser —
// two copies is how a structural guard rots (a fix to one silently
// under-reports in the other). It matches static `import`/`export … from` and
// bare side-effect imports only, never `await import()` (deferred to call time,
// so it can't produce a load-time cycle) and never a specifier inside a comment.
// The walk recurses into subdirectories: a subdirectory module can import back
// up (`agentTuiSpawning/outputSpooler.js` → `../cosAgentLifecycle.js` is a live
// example), so a cycle routed through one subdirectory hop would otherwise be
// invisible here.
// Does `file` reach `mod` with a DEFERRED import? The static graph deliberately
// ignores `import()` — correct for cycle detection, since a deferred import
// cannot produce a load-time cycle — but reaching across a blocked layer that
// way is exactly this cluster's habit, so several guards below need to see it.
// One implementation, because two copies of a structural matcher is how a guard
// rots: a fix to one silently under-reports in the other (the same reason the
// static scan lives once in `server/lib/staticImportGraph.js`).
//
// The match is deliberately loose — anything between the paren and the closing
// paren that names the module — so quotes, template literals, an interleaved
// comment and any path depth all count. `await` is NOT required, so a
// `return import(...).then(...)` back-edge is caught too, and whitespace before
// the paren is allowed because `import ('./x.js')` is valid ESM that a `import\(`
// matcher would wave straight through. A mention inside a comment trips it as
// well; that fails CLOSED, which is the correct bias for a structural guard (the
// alternative is a green suite over a live back-edge).
function importsDynamically(file, mod) {
const src = readFileSync(join(SERVICES_DIR, file), 'utf-8');
return new RegExp(String.raw`\bimport\s*\(\s*[^)]*\b${mod.replace(/\./g, '\\.')}[^)]*\)`).test(src);
}
// What the facade re-exports out of `source`, as `{ declared, exposedAs }` —
// the two sides of `terminateAgent as requestAgentTermination`. `declared` is
// what the defining module calls it; `exposedAs` is the name callers above the
// closure use, which for a renamed export exists ONLY on the facade and so has
// exactly one legitimate source. Both quote styles throughout — `from "./x.js"`
// is valid ESM, and a matcher that only knows `'` reads as green over the exact
// statement it forbids.
//
// One parse shared by every guard that needs the facade's surface, for the same
// reason the static scan lives once in `server/lib/staticImportGraph.js`: two
// copies of a structural matcher is how a guard rots.
const FACADE = 'agentOrchestrator.js';
function reexportedPairs(source) {
const facade = readFileSync(join(SERVICES_DIR, FACADE), 'utf-8');
const block = facade.match(new RegExp(
String.raw`export\s*\{([^}]*)\}\s*from\s*['"]\./${source.replace(/\./g, '\\.')}['"]`));
expect(block, `facade no longer re-exports from ${source} — did the layering change?`).toBeTruthy();
return block[1]
.replace(/\/\/[^\n]*/g, '') // strip the per-export state-edge comments
.split(',')
.map(entry => entry.split(/\s+as\s+/).map(part => part.trim()))
.filter(([declared]) => declared)
.map(([declared, exposedAs]) => ({ declared, exposedAs: exposedAs || declared }));
}
const reexportedFrom = (source) => reexportedPairs(source).map(pair => pair.declared);
// Loaders for the modules whose REAL export surface the guards below assert on.
// Spelled out one literal specifier each rather than `import(`./${name}`)` —
// the bundler cannot analyze a fully-variable specifier and warns, and the point
// of reading the live key list is that it is ground truth, so it should not
// depend on runtime path assembly. Every module here is side-effect-free to
// import (their side effects live behind `init()`/`start()`/`initSpawner()`).
const MODULE_LOADERS = {
'cos.js': () => import('./cos.js'),
'subAgentSpawner.js': () => import('./subAgentSpawner.js'),
'agentLifecycle.js': () => import('./agentLifecycle.js'),
};
const exportedNames = async (mod) => Object.keys(await MODULE_LOADERS[mod]());
// Whichever assertion loads first pays for transforming `cos.js`'s whole service
// graph — measured at 5–10s here depending on machine load, i.e. straddling the
// 10s default, which turns a green guard into an intermittent red one that says
// nothing about the invariant. Every `it()` below that calls `exportedNames`
// carries this, not just the one that happens to run first today.
const MODULE_LOAD_TIMEOUT_MS = 60_000;
describe('agent lifecycle cluster — no static import cycles (#2837)', () => {
const graph = buildStaticImportGraph(SERVICES_DIR);
it('has no static import cycle touching the agent-lifecycle cluster', () => {
const offending = findImportCycles(graph).filter(cycle => CLUSTER.some(m => cycle.includes(m)));
expect(offending, `static import cycle(s) reintroduced:\n${offending.join('\n')}`).toEqual([]);
});
it('keeps the extracted leaves free of back-edges into the cluster orchestrators', () => {
// These exist ONLY to be depended on. If any of them grows an import of
// an orchestrator, the cycle comes straight back — fail loudly and early
// rather than waiting for the graph walk above to go red for a subtler reason.
const orchestrators = ['agentLifecycle.js', 'agentCliSpawning.js', 'agentTuiSpawning.js', 'agentManagement.js', 'subAgentSpawner.js'];
// The TUI spawner's own subdirectory leaves are listed too. The graph walk
// above would catch a STATIC cycle through them (the adapter imports each
// one), but naming them here is what keeps the #8021 seam honest: the
// session controller takes its PTY/spooling/persistence/sentinel/finalize
// collaborators as arguments precisely so it never needs an edge back into
// a spawner, and the cheapest way to lose that is an "it was only one
// import" convenience.
for (const leaf of [
'agentFinalization.js',
'agentRunFinalize.js',
'agentSummaryExtraction.js',
'agentRunnerSync.js',
'agentRunnerOutputBatchers.js',
'agentTuiSpawning/sessionController.js',
'agentTuiSpawning/spawnConfig.js',
'agentTuiSpawning/outputSpooler.js',
'agentTuiSpawning/finalizeHelpers.js',
]) {
const back = (graph.get(leaf) || []).filter(dep => orchestrators.includes(dep));
expect(back, `${leaf} must not import ${back.join(', ')}`).toEqual([]);
}
});
it('keeps prompt section modules as leaves under agentPromptBuilder (#4896)', () => {
const sections = [...graph.keys()].filter(file => file.startsWith('promptSections/'));
expect(sections.length, 'prompt section extraction is missing').toBeGreaterThan(5);
const backEdges = sections.filter(file => (graph.get(file) || []).includes('agentPromptBuilder.js'));
expect(backEdges, `prompt sections must not import agentPromptBuilder.js: ${backEdges.join(', ')}`).toEqual([]);
const sectionCycles = findImportCycles(graph).filter(cycle => sections.some(file => cycle.split(' -> ').includes(file)));
expect(sectionCycles, `prompt section cycle(s) introduced:\n${sectionCycles.join('\n')}`).toEqual([]);
});
it('keeps the agentOrchestrator facade outside the graph it fronts (#3450)', () => {
// The facade only stays a facade while its edges point one way: it imports
// the cluster, the cluster never imports it back.
//
// The forbidden set is derived, not listed. It is everything reachable FROM
// the facade — an import back from any of those closes a loop, and the set
// grows on its own as the cluster does, so it can't fall behind the way a
// hand-maintained list of seven names would (that list omitted
// agentCliSpawning/agentTuiSpawning, both reachable via agentLifecycle).
// Modules outside the closure may import the facade freely: they close no
// loop, and forbidding them would freeze the remaining call-site migrations.
const reachable = new Set();
const walk = (node) => {
for (const dep of graph.get(node) || []) {
if (reachable.has(dep)) continue;
reachable.add(dep);
walk(dep);
}
};
walk('agentOrchestrator.js');
expect(reachable.size, 'facade closure looks empty — did the module move?').toBeGreaterThan(3);
// Deferred imports count as back-edges here too — see `importsDynamically`.
const offenders = [...reachable].filter(file =>
(graph.get(file) || []).includes('agentOrchestrator.js') ||
importsDynamically(file, 'agentOrchestrator.js')
).sort();
expect(offenders, `agentOrchestrator.js must not be imported by ${offenders.join(', ')}`).toEqual([]);
});
it('no longer needs the state-layer forwarders into the process layer (#3450)', async () => {
// Step 4 of the #3450 sequencing. `cosAgentLifecycle.js` — the agent STATE
// layer — used to forward pause/kill/stats into the PROCESS layer with
// `await import()`, purely so a caller holding a `cos.js` handle could reach
// across a boundary the state layer cannot import across statically. Those
// callers go through the facade now.
//
// Guard the mechanism, not the three names: ANY deferred import of
// `agentManagement.js` from here is a new forwarder. A *static* one needs no
// assertion — it closes a cycle the walk above already fails on.
expect(importsDynamically('cosAgentLifecycle.js', 'agentManagement.js'),
'cosAgentLifecycle.js must not defer-import the process layer — ask the facade').toBe(false);
// The other half: `cos.js` re-exporting those transitions is what gave the
// forwarders callers in the first place. Derive which names are off-limits
// from the facade itself — everything it takes from the process layer —
// rather than listing them, so the rule tracks the facade as it grows.
//
// Minus the names the facade ALSO serves from the state layer. That set is
// `terminateAgent`, the one genuine collision in this cluster: `cos.js`
// legitimately re-exports the state-layer function of that name, and it is
// only unambiguous inside the facade because the facade renames it to
// `requestAgentTermination`. Subtracting is what keeps this derivation from
// failing on a name `cos.js` is right to export.
// Both quote styles throughout — `from "./x.js"` is valid ESM, and a matcher
// that only knows `'` reads as green over the exact statement it forbids.
const stateLayer = new Set(reexportedFrom('cosAgentLifecycle.js'));
const forbidden = reexportedFrom('agentManagement.js').filter(name => !stateLayer.has(name));
expect(forbidden.length, 'derived nothing to forbid — check the facade export blocks').toBeGreaterThan(0);
// Then assert against each barrel's REAL export surface, not its source
// text. Every regex for this was bypassable by a form it did not anticipate
// — a second re-export statement, a different source module, double quotes,
// `export *`, `import` + a bare `export { … }` with no `from` at all. The
// module's own key list is ground truth and has no syntax to outrun.
//
// `subAgentSpawner.js` joined this loop in #3450. It used to be excluded on
// purpose — it re-exported the same three transitions as its back-compat
// barrel, so the rule could only be stated for `cos.js`. With that barrel
// retired the rule generalizes, which is the point of having retired it.
for (const barrel of ['cos.js', 'subAgentSpawner.js']) {
const barrelExports = await exportedNames(barrel);
expect(barrelExports, `${barrel} exports nothing — did the import fail?`).not.toEqual([]);
for (const name of forbidden) {
expect(barrelExports, `${barrel} must not re-export ${name} — it is a process-layer transition, ask the facade`)
.not.toContain(name);
}
}
}, MODULE_LOAD_TIMEOUT_MS);
it('keeps the cluster orchestrators from re-growing a re-export barrel (#3450)', async () => {
// `subAgentSpawner.js` re-exported ~40 symbols from nine siblings, and
// `agentLifecycle.js` re-exported the leaves that had been extracted out of
// it for that barrel to forward. So "where does finalizeAgent live" had
// three answers, and a caller could reach a transition through a module that
// merely forwards it. Both surfaces are gone; this keeps them gone.
//
// Stated as "every export is DECLARED here", which is the only form that
// survives contact with the syntax: `export *`, `export { x } from …`, and
// `import` + a bare `export { x }` all fail it identically, and so does a
// re-export from a module this test has never heard of. The real key list is
// ground truth for what is exported; the source scan only answers what is
// declared, and if that scan ever misses a legitimate local declaration the
// test fails LOUD rather than going green over a live re-export.
for (const mod of ['subAgentSpawner.js', 'agentLifecycle.js']) {
const src = readFileSync(join(SERVICES_DIR, mod), 'utf-8');
const declared = new Set(
[...src.matchAll(/^export\s+(?:async\s+)?(?:function\s*\*?|const|let|var|class)\s+([A-Za-z0-9_$]+)/gm)]
.map(m => m[1])
);
const actual = await exportedNames(mod);
expect(actual, `${mod} exports nothing — did the import fail?`).not.toEqual([]);
const forwarded = actual.filter(name => !declared.has(name)).sort();
expect(forwarded,
`${mod} must declare what it exports — ${forwarded.join(', ')} is forwarded from another module; import it from the one that defines it`
).toEqual([]);
}
}, MODULE_LOAD_TIMEOUT_MS);
it('makes every transition caller name the facade or the defining module, never a barrel (#3450)', () => {
// Step 3 of the #3450 sequencing, for the callers the "move the caller out"
// recipe cannot reach. `agentManagement.js` and `agentLifecycle.js` DEFINE
// transitions the facade re-exports, and `agentFinalization.js` /
// `agentCliSpawning.js` are leaves those two must call — all four sit inside
// the facade's closure permanently, so importing the facade is a cycle, not
// an option. What is still achievable there is the property the facade was
// built for: ONE address per transition. Above the closure that address is
// the facade; inside it, the module that declares the function. A barrel is
// never an answer — that is the third address this sequencing keeps deleting.
//
// Derived from the facade's own export blocks, so a transition added there
// is guarded the moment it lands and `agentOrchestrator.js` stays the only
// file anyone edits to change the rule.
const declaringModules = ['agentManagement.js', 'cosAgentLifecycle.js', 'agentLifecycle.js'];
const declaredBy = new Map(); // transition name → the modules allowed to serve it
const allow = (name, source) => {
if (!declaredBy.has(name)) declaredBy.set(name, new Set());
declaredBy.get(name).add(source);
};
for (const source of declaringModules) {
for (const { declared, exposedAs } of reexportedPairs(source)) {
allow(declared, source);
// A RENAMED export (`terminateAgent as requestAgentTermination`) has a
// public name that exists nowhere but the facade, so the facade is its
// only legitimate source. Registering it is what stops a barrel from
// re-exporting the alias and slipping past a map keyed on `terminateAgent`.
if (exposedAs !== declared) allow(exposedAs, FACADE);
}
}
// `terminateAgent` lands in two declaring modules: the process-side one and
// the state-side one the facade renames. Both are real definitions, so both
// stay allowed — the rule here is "not a barrel", and that collision is a
// naming question the facade already answered.
expect(declaredBy.size, 'derived no transitions — check the facade export blocks').toBeGreaterThan(3);
expect([...declaredBy.keys()], 'the facade rename is no longer covered — check reexportedPairs')
.toContain('requestAgentTermination');
// A FORWARDER is any module that re-exports its way to a declaring module, at
// any depth. None remain: `cosAgents.js` was retired in #3450 and `cos.js`'s
// agent re-export block was the last one. Walking the re-export edges rather
// than listing barrels means a NEW barrel is covered the day it is written.
const reexportEdges = (file) => [
...readFileSync(join(SERVICES_DIR, file), 'utf-8')
.matchAll(/export\s*(?:\*|\{[^}]*\})\s*(?:as\s+\w+\s*)?from\s*['"]([^'"]+)['"]/g)
].map(m => relative(SERVICES_DIR, resolve(dirname(join(SERVICES_DIR, file)), m[1])));
const forwarders = new Set();
for (const file of graph.keys()) {
if (file === FACADE || declaringModules.includes(file)) continue; // both are answers, not forwarders
const seen = new Set([file]);
const queue = [file];
while (queue.length) {
for (const target of reexportEdges(queue.pop())) {
if (seen.has(target) || !graph.has(target)) continue;
if (declaringModules.includes(target)) { forwarders.add(file); queue.length = 0; break; }
seen.add(target);
queue.push(target);
}
}
}
expect([...forwarders].sort(), 'a barrel forwards a transition again — import the declaring module instead')
.toEqual([]);
// Production sources only. A test mirrors whatever its subject imports (a
// mock pointed at a module the subject no longer imports silently stops
// applying), so tests follow this rule rather than defining it.
const allowed = new Set([FACADE, ...declaringModules]);
const offenders = [];
for (const file of graph.keys()) {
if (file === FACADE) continue;
const src = readFileSync(join(SERVICES_DIR, file), 'utf-8');
const resolveSpec = (spec) => relative(SERVICES_DIR, resolve(dirname(join(SERVICES_DIR, file)), spec));
// Named imports — `import { completeAgent as done } from './cos.js'`. The
// binding's LEFT side is the transition name; renaming it on the way in
// does not change where it came from.
for (const [, names, spec] of src.matchAll(/import\s*\{([^}]*)\}\s*from\s*['"]([^'"]+)['"]/g)) {
const target = resolveSpec(spec);
if (allowed.has(target)) continue;
for (const entry of names.split(',')) {
const name = entry.split(/\s+as\s+/)[0].trim();
if (!declaredBy.has(name) || declaredBy.get(name).has(target)) continue;
offenders.push(`${file} imports ${name} from ${target}`);
}
}
// DEFERRED forms. `await import()` is invisible to the static graph — by
// design, it cannot produce a load-time cycle — but reaching across a
// blocked layer with one is this cluster's whole habit, and the exact
// pattern this PR deleted from `cleanupOrphanedAgents` was
// `const { completeAgent } = await import('./cos.js')`. A guard that only
// reads static syntax would go green the day someone writes it again.
// In a destructure the LEFT of `a: b` is the exported name, same role `as`
// plays in a static import.
for (const [, names, spec] of src.matchAll(/(?:const|let|var)\s*\{([^}]*)\}\s*=\s*(?:await\s+)?import\s*\(\s*['"]([^'"]+)['"]\s*\)/g)) {
const target = resolveSpec(spec);
if (allowed.has(target)) continue;
for (const entry of names.split(',')) {
const name = entry.split(':')[0].trim();
if (!declaredBy.has(name) || declaredBy.get(name).has(target)) continue;
offenders.push(`${file} defer-imports ${name} from ${target}`);
}
}
// `(await import('./cos.js')).completeAgent` — the same reach, one step
// shorter. `?.` and `['name']` are the same property read to the engine,
// so a matcher that only knows the dot reads green over both.
for (const [, spec, dotted, bracketed] of src.matchAll(
/import\s*\(\s*['"]([^'"]+)['"]\s*\)[\s)]*(?:\?)?(?:\.\s*(\w+)|\.?\s*\[\s*['"`](\w+)['"`]\s*\])/g)) {
const name = dotted || bracketed;
const target = resolveSpec(spec);
if (allowed.has(target) || !declaredBy.has(name) || declaredBy.get(name).has(target)) continue;
offenders.push(`${file} defer-imports ${name} from ${target}`);
}
// HANDLES onto a whole module — `import * as cos from './cos.js'` and its
// deferred twin `const cos = await import('./cos.js')`. Neither names a
// binding, so the loops above cannot see them, yet each hands the caller
// every transition the barrel forwards. Banning the handle outright is too
// blunt (that is how a dozen modules reach the task store, which is not
// this issue's business), so check the two ways a transition comes back
// OFF it: a property read and a destructure. Both, because either one
// alone reads green over the other — and the property read covers `?.`
// and `['name']` alongside the dot, since all three compile to the same
// access and a dot-only matcher waves the other two straight through.
const handles = [
...src.matchAll(/import\s*\*\s*as\s+(\w+)\s*from\s*['"]([^'"]+)['"]/g),
...src.matchAll(/(?:const|let|var)\s+(\w+)\s*=\s*(?:await\s+)?import\s*\(\s*['"]([^'"]+)['"]\s*\)/g),
];
for (const [, ns, spec] of handles) {
const target = resolveSpec(spec);
if (!forwarders.has(target)) continue;
for (const name of declaredBy.keys()) {
const reached = new RegExp(
String.raw`\b${ns}\s*(?:\?)?(?:\.\s*${name}\b|\.?\s*\[\s*['"\`]${name}['"\`]\s*\])`).test(src)
|| new RegExp(String.raw`\{[^}]*\b${name}\b[^}]*\}\s*=\s*(?:await\s+)?${ns}\b`).test(src);
if (reached) offenders.push(`${file} reaches ${name} through the forwarder ${target}`);
}
}
}
expect(offenders.sort(),
`a transition must come from the facade or the module that declares it:\n${offenders.join('\n')}`
).toEqual([]);
});
it('keeps agentState.js an import-free leaf, so agents.js can use the facade (#3450)', () => {
// `agentState.js` is what lets modules that cannot import each other share
// state — the pid map moved here so `agentManagement.js` no longer had to
// import it out of `agents.js`. One import of a cluster module here would
// close a cycle for every such pair at once, so it must stay import-free.
expect(graph.get('agentState.js')).toEqual([]);
// The payoff: with that back-edge gone, agents.js is outside the facade's
// closure and reaches the kill transition through a plain static import.
expect(importsDynamically('agents.js', 'subAgentSpawner.js'),
'agents.js must not defer-import the spawner barrel — the facade is a static import now').toBe(false);
expect(graph.get('agents.js')).toContain('agentOrchestrator.js');
});
it('keeps cos.js out of every static import cycle (#5684)', () => {
// cos.js used to re-export cosState/cosTaskStore. Two leaf services reached
// THROUGH that barrel for one symbol each (memoryEmbeddings -> getConfig, character -> the task data),
// and because cos.js transitively reaches the CoS tool registry -> voice
// tools -> askService -> both of those leaves, each one-symbol forward closed
// a 7-module ring. Both now import the DECLARING module, which is the same
// rule the transition-caller guard above enforces for the agent cluster.
const offending = findImportCycles(graph).filter(cycle => cycle.split(' -> ').includes('cos.js'));
expect(offending, `cos.js is back in a static import cycle:\n${offending.join('\n')}`).toEqual([]);
// Name the two back-edges directly, so a reintroduced one-symbol import of
// the barrel fails with the reason rather than as an opaque ring.
expect(graph.get('memoryEmbeddings.js'), 'memoryEmbeddings must import getConfig from cosState.js').not.toContain('cos.js');
expect(graph.get('memoryEmbeddings.js')).toContain('cosState.js');
expect(graph.get('character.js'), 'character must import the completed-task summaries from cosTaskRepository.js').not.toContain('cos.js');
expect(graph.get('character.js')).toContain('cosTaskRepository.js');
});
it('no longer needs the dynamic-import workaround for handleOrphanedTask', () => {
// The cycle-dodge this issue was filed for: agentLifecycle reached
// agentManagement via `await import()` because agentManagement imported it back.
expect(importsDynamically('agentLifecycle.js', 'agentManagement.js')).toBe(false);
expect(graph.get('agentLifecycle.js')).toContain('agentManagement.js');
});
});