Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

42.4 KB
Raw Blame
/**
 * The daemon's shape, checked: master, core, services (cli/AGENTS.md). People and their coding agents
 * build features in parallel on it, and a rule nobody checks is a rule the next change breaks quietly.
 * So the boundaries are tests: a service reaches the core only through `core/api.ts`, the core never
 * reaches into a service, the master holds no feature code, and the two files every change used to land
 * in — `runForeground` and the socket's request switch — remain wiring and transport.
 * Source size is reported for review; dependencies and behavior enforce the architecture.
 *
 * When this fails, the message says where the code belongs. Move it there; do not widen the rule.
 */
import { readdirSync, readFileSync, statSync } from 'node:fs'
import { dirname, join, relative, resolve } from 'node:path'
import ts from 'typescript'
import { describe, expect, it } from 'vitest'
import { OTHER_ENGINES } from './engines/inProcess.js'

const SRC = __dirname

interface Import {
  file: string
  from: string
  typeOnly: boolean
}

/** Every import and re-export in a folder's source (not its tests), and whether it is types only. */
function importsIn(folder: string): Import[] {
  const found: Import[] = []
  const walk = (dir: string): void => {
    for (const entry of readdirSync(dir, { withFileTypes: true })) {
      const path = join(dir, entry.name)
      if (entry.isDirectory()) { walk(path); continue }
      if (!entry.name.endsWith('.ts') || entry.name.endsWith('.spec.ts') || entry.name.endsWith('.test.ts')) continue
      const source = ts.createSourceFile(path, readFileSync(path, 'utf8'), ts.ScriptTarget.Latest, true)
      for (const statement of source.statements) {
        if ((ts.isImportDeclaration(statement) || ts.isExportDeclaration(statement)) && statement.moduleSpecifier && ts.isStringLiteral(statement.moduleSpecifier)) {
          let typeOnly = false
          if (ts.isImportDeclaration(statement)) {
            const clause = statement.importClause
            const named = clause?.namedBindings && ts.isNamedImports(clause.namedBindings) ? clause.namedBindings.elements : null
            typeOnly = !!clause && (clause.isTypeOnly || (!clause.name && !!named && named.length > 0 && named.every((element) => element.isTypeOnly)))
          } else {
            typeOnly = statement.isTypeOnly
          }
          found.push({ file: relative(SRC, path), from: statement.moduleSpecifier.text, typeOnly })
        }
      }
    }
  }
  walk(join(SRC, folder))
  return found
}

/** The lines `runForeground` spans in core/main.ts. */
function runForegroundLines(): number {
  const lines = readFileSync(join(SRC, 'core', 'main.ts'), 'utf8').split('\n')
  const start = lines.findIndex((line) => line.startsWith('async function runForeground('))
  const end = lines.findIndex((line, index) => index > start && line === '}')
  return end - start
}

/** The relative modules a source imports for its values: static, re-exported, bare and dynamic; never `import type`. */
function valueImports(path: string, text: string): string[] {
  return importsFor(path, text).map(({ from }) => from)
}

/** `valueImports`, saying which are dynamic (`import('…')`). */
function importsFor(path: string, text: string): Array<{ from: string; dynamic: boolean }> {
  const found: Array<{ from: string; dynamic: boolean }> = []
  const visit = (node: ts.Node): void => {
    if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier)) {
      let typeOnly: boolean
      if (ts.isImportDeclaration(node)) {
        const clause = node.importClause
        const named = clause?.namedBindings && ts.isNamedImports(clause.namedBindings) ? clause.namedBindings.elements : null
        typeOnly = !!clause && (clause.isTypeOnly || (!clause.name && !!named && named.length > 0 && named.every((element) => element.isTypeOnly)))
      } else {
        typeOnly = node.isTypeOnly
      }
      if (!typeOnly) found.push({ from: node.moduleSpecifier.text, dynamic: false })
    } else if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword && node.arguments[0] && ts.isStringLiteralLike(node.arguments[0])) {
      found.push({ from: node.arguments[0].text, dynamic: true })
    }
    ts.forEachChild(node, visit)
  }
  visit(ts.createSourceFile(path, text, ts.ScriptTarget.Latest, true))
  return found.filter(({ from }) => from.startsWith('.'))
}

/**
 * The one import the core's walk does not follow: the services that run in a process of their own by
 * default, loaded into the core's only when they run there instead (services/inline.ts). Only a dynamic
 * import of it is passed over; a static one would load it in every core, and is walked.
 */
const IN_PROCESS_ONLY = 'services/inline.ts'

/**
 * The Swarm's doors: the only imports of its code from outside it, each dynamic and taken only while the Swarm is on
 * (`HARNESS_SWARM`, harnessd/swarmSwitch.ts), or, for the CLI's own commands, only when one is run. A walk passes over
 * them, so a process with the Swarm off loads none of its code; a static import of the same file is walked.
 */
const SWARM_DOORS: Readonly<Record<string, readonly string[]>> = {
  // The Swarm's internal pre-command hook: loaded only for that command, without starting any daemon.
  'entry.ts': ['superTabs/shellGuardHook.ts'],
  // Its side of the core's process, and of the services that act on it when they run there.
  'core/main.ts': ['superTabs/inCore.ts', 'superTabs/inServices.ts'],
  // Its side of the services that act on it, in their own processes, and its own service's process, which the master
  // starts only while it is on (harnessd/services.ts `servicesOn`).
  'serviceProcess.ts': ['superTabs/inServices.ts', 'services/superTabsProcess.ts'],
  // `harness super-tab` and git's credential helper in a Swarm session: from the sources every daemon process runs cli.ts.
  'cli.ts': ['superTabs/command.ts', 'superTabs/gitCredential.ts'],
}
/** The Swarm's code (Super Tabs): its folder, its libraries and its service. */
const isSwarmCode = (file: string): boolean => /^superTabs\//.test(file) || /^lib\/swarm/.test(file) || /^services\/superTabs(Process)?\.ts$/.test(file)

/**
 * The files whose `import()`s the core's walk does not follow: the loader of the other twelve engines' code,
 * which the core loads in its own process only once one of their sessions needs it
 * (docs/design/2026-10-08-other-engines-out-of-core.md). An `import()` of their code anywhere else is followed.
 */
const LAZY_LOADERS = new Set(['engines/inProcess.ts'])

/**
 * The code a process started on `entry` runs: every file its imports reach, as each file's lines
 * (docs/design/2026-10-06-core-boundary-next.md, "The target, and its test"). It follows static and
 * dynamic imports under src, `.js` to `.ts` and folders to their index, and leaves out `import type`
 * (types cost nothing at run time), tests, a dynamic import of `IN_PROCESS_ONLY`, and the `import()`s written
 * in `LAZY_LOADERS`.
 */
function closureOf(entry: string): Map<string, number> {
  const lines = new Map<string, number>()
  const pending = [join(SRC, entry)]
  while (pending.length > 0) {
    const path = pending.pop()!
    const file = relative(SRC, path)
    if (lines.has(file)) continue
    const parsed = parsedFile(path)
    lines.set(file, parsed.lines)
    pending.push(...parsed.imports)
  }
  return lines
}

/** Whether the walk follows an import of `target` written in `importer`: every one but an `import()` of
 *  `IN_PROCESS_ONLY`, one through a Swarm door (`SWARM_DOORS`), or one written in a lazy loader. */
function followed(importer: string, target: string, dynamic: boolean): boolean {
  return !dynamic || (target !== IN_PROCESS_ONLY && !SWARM_DOORS[importer]?.includes(target) && !LAZY_LOADERS.has(importer))
}

/** Each file read and parsed once, however many walks pass through it. */
const parsed = new Map<string, { lines: number; imports: string[] }>()
function parsedFile(path: string): { lines: number; imports: string[] } {
  const known = parsed.get(path)
  if (known) return known
  const isFile = (candidate: string): boolean => { try { return statSync(candidate).isFile() } catch { return false } }
  const text = readFileSync(path, 'utf8')
  const imports: string[] = []
  for (const { from, dynamic } of importsFor(path, text)) {
    const base = resolve(dirname(path), from)
    const target = [base.replace(/\.js$/, '.ts'), base, `${base}.ts`, join(base, 'index.ts')].find(isFile)
    if (!target || !target.startsWith(SRC + '/') || !target.endsWith('.ts') || /\.(spec|test|e2e)\.ts$/.test(target)) continue
    if (!followed(relative(SRC, path), relative(SRC, target), dynamic)) continue
    imports.push(target)
  }
  const result = { lines: text.split('\n').length, imports }
  parsed.set(path, result)
  return result
}

/** Walking the whole CLI parses some 500 files: seconds on a busy machine, not the default five. */
const WALK_TIMEOUT_MS = 60_000

/** Exceptions, each with its reason. Keep this short. */
const SERVICE_MAY_IMPORT: Record<string, string> = {
  // A pure function of a session row. Move it out of registry.ts when workspaces leaves the core's process.
  'services/workspaces.ts → ../lib/registry.js': 'sessionDisplayTitle, a pure helper',
}

/** Claude Code's and Codex's declared contracts that core reads in line: what a launch's, discovery's or session
 *  repair's closure may reach of the two engines. */
const LAUNCH_CONTRACTS = new Set(['engines/claude/launch.ts', 'engines/codex/launch.ts'])
const SESSION_STORES = new Set(['engines/claude/sessionStore.ts', 'engines/codex/sessionStore.ts'])
const DECLARED = new Set(['engines/claude/hookContract.ts', 'engines/codex/hookContract.ts', 'engines/claude/discoveryContract.ts',
  'engines/codex/discoveryContract.ts', ...SESSION_STORES])

/** What is not the core's, by path: each goes to a service or its own process, in the plan's order. */
const EDGE: RegExp[] = [
  /^engines\/(claude|codex)\/(screen|composer|activity|stoppedGoal|modelControl|modelPicker|questionControl|submission|nativeControl)\.ts$/,
  // Claude Code's and Codex's hooks are declared data (hookContract.ts) that the kit applies in core: no hook code
  // of theirs is the core's, and none runs in a worker either (docs/design/2026-10-08-engine-hooks.md).
  /^engines\/(claude|codex)\/(hooks|installHooks)\.ts$/,
  // Their launch specifics are declared data too (launch.ts): Codex's startup probe and retry and its own-login
  // provider are the kit's, in core, and never a worker's (docs/design/2026-10-08-engine-launch.md).
  /^engines\/codex\/ownLoginProvider\.ts$/, /^lib\/codexStartupRetry\.ts$/,
  // So is their launch preparation: folder trust and the resume repair are declared, and the kit applies them.
  /^engines\/codex\/portableHistory\.ts$/, /^lib\/claudeTrust\.ts$/,
  // And what discovery reads off their processes and transcripts (discoveryContract.ts, applied by the kit).
  /^lib\/(claudeProject|codexHomeProbe)\.ts$/,
  /^lib\/(askQuestion|runtimeProfileController|composerScreen|teamWriteHold|messageHold|terminalActivity|codexTurnRecovery)\.ts$/,
  /^engines\/(screens|modelControls|questionControls|submissions|nativeControls)\.ts$/,
  // Claude Code's and Codex's reading of their composer: shared by the two, loaded only by their workers.
  /^engines\/kit\/nativeSubmission\.ts$/,
  // A worker's request handlers, the submission readers' among them, run in the engine's own process.
  /^engines\/worker\/\w+Requests\.ts$/,
  // The pilot reader implementations and their host are never loaded by supervised core.
  /^engines\/(worker\/process|transcripts|(claude|codex)\/(transcript|\w+ReaderProcess))\.ts$/,
  // Nor their transcripts' normalizers, Codex's rollout and sub-agent readers, or what replays their history: their
  // readers' and live parsers', in their workers. Core reads only what they declare: adoption, activity and
  // their stores (docs/design/2026-10-08-engine-launch.md, (c5)). Search's normalizer table is search's.
  /^engines\/(claude|codex)\/(normalize|normalizer|subagent|subagentStats|rollout|lastTurn|live|attach)\.ts$/,
  /^lib\/(normalize|transcriptReader)\.ts$/, /^lib\/sessionSearch\/externals\/(claude|codex)\.ts$/,
  /^engines\/(runtime|(claude|codex)\/runtimeProfile)\.ts$/, /^lib\/runtimeProfile\.ts$/,
  /^gateway\//, /^lib\/e2ee\//, /^cable\//, /^device\//, /^lib\/autonomous-device\//, /^sharing\//, /^orchestrator\//, /^services\//,
  // The Swarm (Super Tabs) is a subsystem that can be switched off: the core loads its code only through its doors.
  /^superTabs\//,
  /^lib\/grid(Attach|Credentials|Derive|Ensure|Envelope|Exec|FleetRpc|Handoff|Install|McpUrl|Models|ModelsPayload|Picture|Presence|Reader|Target|Wake)\.ts$/,
  /^lib\/localModels\.ts$/,
  // The grid and saved-API launch builders are models': the core asks it for a launch (ModelsPort.gridLaunch) and keeps
  // only the wire it checks one with and the lists every launch reads (lib/gridLaunchWire.ts), so a launch on the
  // engine's own login loads none of them (docs/design/2026-10-08-launch-port.md, (L1)).
  /^lib\/(gridLaunch|gridWebMcp|apiModels|gridAssignment|apiConnections)\.ts$/,
  // The change-agent handoff reads and redacts history and runs git: the edge host owns that work.
  /^lib\/agentHandoff\.ts$/,
  // Usage owns all aggregate readers and ledgers. Core reads validated wire snapshots only.
  /^lib\/(agentTokenUsage|agentOutputStats|sessionWork)\.ts$/,
  // The relay's own parts, the gateway's alone: the windows' sessions to other machines, P2P and STUN, the
  // remote viewers' proxy, and the shaping of what goes up the link.
  /^lib\/(remoteRelay|terminalP2p|stunSelect|remoteViewerProxy|deviceRecentTrim|commanderReplay)\.ts$/,
  // The viewers' own: a viewer served to a client over its connection, and the stream it runs on.
  /^lib\/(viewerForwarder|interactiveViewer|viewerWire)\.ts$/,
  // The recaps' own parts: the mirror that cuts each turn's recap and card, and the notification policy it
  // shares with the questions the core tells it of (services/recaps.ts).
  /^lib\/(commander|agentNotifications)\.ts$/,
  // Package execution belongs to the Store; core retains the installed index and launch contracts.
  /^dsh\/(catalog|install|update|updates|registry|wire|service|lock|builtins|viewer|viewerLedger|verdict|artifacts|runtime|materialize|shell|preparation)\.ts$/,
  // Search owns external catalogs and provider reads too. Core keeps only the wire's declared types.
  /^lib\/sessionSearch\/(?!externals\/types\.ts$)/,
  // Downloading builds: the updater's, in a process the master runs (services/updaterProcess.ts). The core
  // never downloads a build.
  /^lib\/(selfUpdate|runtimeInstall)\.ts$/, /^tui\/(update|install)\.ts$/,
]

/**
 * The edge files the core's process still loads, each with the step of the plan that takes it out. The
 * list only shrinks: an entry no longer reached fails the test, so remove it with the move that ends it.
 */
const CORE_MAY_REACH: Record<string, string> = {}

/** The other twelve engines' own files: their folders but for the data they declare, their search readers, and the
 *  shared files that hold only their code. */
const OTHERS = `(${OTHER_ENGINES.join('|')})`
const THEIRS: RegExp[] = [
  new RegExp(`^engines/${OTHERS}/(?!contract\\.ts$)`),
  new RegExp(`^lib/sessionSearch/externals/${OTHERS}\\.ts$`),
  /^lib\/(hooks|questionPane|legacyScreen|legacyPane|hermesHome|databaseHistory)\.ts$/,
]
const theirs = (file: string): boolean => THEIRS.some((pattern) => pattern.test(file))

/**
 * The other engines' files the core's process still loads, each with the sub-batch of the plan that takes it out
 * (docs/design/2026-10-08-other-engines-out-of-core.md, section 5). The list only shrinks: an entry no longer
 * reached fails the test, so remove it with the move that ends it. Empty, the core loads none of their code.
 */
const OTHER_ENGINES_CORE_MAY_REACH: Record<string, string> = {}

/** Core's entries for each facet, and the sub-batch after which they reach none of the other engines' files. */
const FACETS_FREE_OF_THEM: Array<[string, string]> = [
  ['core/engines/screens.ts', '(o1)'],
  ['lib/questionController.ts', '(o1)'],
  // The live path, history and the last turn; and the core's own files that once held their code: Cursor's
  // Task hooks, built from its code on first use, agy's backstop, and the database engines' history.
  ['core/transcripts/ingest.ts', '(o3)'],
  ['core/transcripts/attach.ts', '(o3)'],
  ['core/transcripts/history.ts', '(o3)'],
  ['core/transcripts/lastTurn.ts', '(o3)'],
  ['core/transcripts/databaseHistory.ts', '(o3)'],
  ['core/engines/cursorTasks.ts', '(o3)'],
  ['core/turns/agyBackstop.ts', '(o3)'],
  // What the core reads of their model and effort, and how a switch of theirs would be driven.
  ['lib/runtimeProfileState.ts', '(o4)'],
  ['lib/runtimeControl.ts', '(o4)'],
  // Where their conversations are: the registry's layouts and Cursor's homes, declared; bind's finders and
  // repair's readers, loaded; Cursor's discovery and its queued Tasks, built on first use; Hermes's store.
  ['lib/registry.ts', '(o6)'],
  ['core/agents/bind.ts', '(o6)'],
  ['lib/sessionRepair.ts', '(o6)'],
  ['core/engines/cursorDiscovery.ts', '(o6)'],
  ['core/agents/forget.ts', '(o6)'],
  ['core/turns/turnHooks.ts', '(o6)'],
  ['engines/kit/notifyHooks.ts', '(o6)'],
  ['lib/sessionCheckpoint.ts', '(o6)'],
  ['lib/purgeAgentService.ts', '(o6)'],
  // Hermes's admission and homes, declared and read by the kit; its home probe, loaded for a Hermes process.
  ['hookServer.ts', '(o6)'],
  ['core/engines/hooks.ts', '(o6)'],
  ['lib/terminalAgentDiscovery.ts', '(o6)'],
  // The launches: OpenCode's v2 rule declared, its version probe and session-model writer loaded for OpenCode.
  ['core/agents/create.ts', '(o6)'],
  ['core/agents/fork.ts', '(o6)'],
  ['core/agents/launches.ts', '(o6)'],
  ['core/agents/retarget.ts', '(o6)'],
  ['core/agents/restart.ts', '(o6)'],
  ['lib/launchOverrides.ts', '(o6)'],
  ['lib/engineLaunch.ts', '(o6)'],
  ['lib/gridLaunch.ts', '(o6)'],
  ['lib/subscriptionModel.ts', '(o6)'],
  // Search's provider composition still loads each engine lazily in its own process.
  ['lib/sessionSearch/externals/index.ts', '(o5)'],
  ['lib/sessionSearch/external.ts', '(o5)'],
  ['core/agents/adopt.ts', '(o5)'],
]

describe('the daemon\'s shape', () => {
  it('a service reaches the core only through core/api.ts: never a core module, the registry, cli.ts or the socket', () => {
    const wrong = importsIn('services').filter(({ file, from, typeOnly }) => {
      if (SERVICE_MAY_IMPORT[`${file} → ${from}`]) return false
      if (/(^|\/)core\//.test(from)) return from !== '../core/api.js'
      if (/(^|\/)(cli|backendSocket|localWsServer)\.js$/.test(from)) return true
      if (/(^|\/)lib\/registry\.js$/.test(from)) return !typeOnly
      return false
    }).map(({ file, from }) => `${file} imports ${from}`)
    expect(wrong, 'A service may use the core only through CoreApi (src/core/api.ts). If CoreApi lacks it, add it there in its own change (src/services/AGENTS.md).').toEqual([])
  })

  it('the core never reaches into a service, cli.ts or the socket, but for types', () => {
    // core/main.ts is the composition root: it builds the socket and starts the services, so it is the one
    // core file that imports them. Which of their files the core's process loads is the closure's test
    // (below), file by file. It never imports cli.ts: that would put the CLI back into the core.
    const wrong = importsIn('core').filter(({ file, from, typeOnly }) =>
      (file === 'core/main.ts' ? /(^|\/)cli\.js$/.test(from)
        : /(^|\/)services\//.test(from) || (/(^|\/)(cli|backendSocket|localWsServer)\.js$/.test(from) && !typeOnly)))
      .map(({ file, from }) => `${file} imports ${from}`)
    expect(wrong, 'The core calls services only through CorePorts, and is handed the socket\'s pieces as dependencies (src/core/AGENTS.md).').toEqual([])
  })

  it('the core imports nothing of the Swarm\'s, not even its types: its code is loaded only while it is on', () => {
    // Dee's rule (v1's last item): the daemon core stays small and reliable, and the Swarm is a subsystem that can be
    // switched off. What the core needs of it is in core/api.ts; what the Swarm runs in the core's process is
    // handed in by the core's entry from its doors, imported dynamically and only while the Swarm is on.
    const wrong = importsIn('core').filter(({ from }) => /(^|\/)superTabs\//.test(from) || /(^|\/)lib\/swarm/.test(from))
      .map(({ file, from }) => `${file} imports ${from}`)
    expect(wrong, 'Declare what the core needs of the Swarm in core/api.ts, and hand its code in from superTabs/inCore.ts.').toEqual([])
    const main = importsFor('core/main.ts', readFileSync(join(SRC, 'core', 'main.ts'), 'utf8')).filter(({ from }) => /(^|\/)superTabs\//.test(from))
    expect(main).toEqual([{ from: '../superTabs/inCore.js', dynamic: true }, { from: '../superTabs/inServices.js', dynamic: true }])
    expect(followed('core/main.ts', 'superTabs/inCore.ts', true)).toBe(false)
    expect(followed('core/main.ts', 'superTabs/inCore.ts', false)).toBe(true)
    expect(followed('services/models.ts', 'superTabs/inServices.ts', true)).toBe(true)
  }, WALK_TIMEOUT_MS)

  // The review of #1765: with the Swarm off, every core still loaded its skills through the registry, and with every
  // service in the core's process (`HARNESSD_SERVICES=none`) its retention, observers and grid code, and the agent cleanup
  // kept its members. Every import of its code from outside it is now a door, and no process's start reaches it.
  it('with the Swarm off no process loads its code, imports included: its code is reached only through its doors', () => {
    const resolveFrom = (file: string, from: string): string => {
      const base = resolve(dirname(join(SRC, file)), from)
      return relative(SRC, [base.replace(/\.js$/, '.ts'), `${base}.ts`, join(base, 'index.ts')].find((candidate) => { try { return statSync(candidate).isFile() } catch { return false } }) ?? base)
    }
    const sources = (dir: string): string[] => readdirSync(join(SRC, dir), { withFileTypes: true }).flatMap((entry) => entry.isDirectory()
      ? sources(join(dir, entry.name)) : /\.ts$/.test(entry.name) && !/\.(spec|test|e2e)\.ts$/.test(entry.name) ? [join(dir, entry.name)] : [])
    const outside = sources('.').filter((file) => !isSwarmCode(file) && !file.startsWith('testing/'))
    const doors = outside.flatMap((file) => importsFor(file, readFileSync(join(SRC, file), 'utf8'))
      .map(({ from, dynamic }) => ({ file, target: resolveFrom(file, from), dynamic })).filter(({ target }) => isSwarmCode(target)))
    expect(doors.filter(({ file, target, dynamic }) => !dynamic || !SWARM_DOORS[file]?.includes(target)).map(({ file, target }) => `${file} imports ${target}`),
      'Hand the Swarm\'s code in through superTabs/inCore.ts or superTabs/inServices.ts, loaded only while it is on.').toEqual([])
    expect(doors.map(({ file, target }) => `${file} → ${target}`).sort()).toEqual(Object.entries(SWARM_DOORS).flatMap(([file, targets]) => targets.map((target) => `${file} → ${target}`)).sort())
    // The core (normal and inline), the master, the services' process and each service: none reaches the Swarm's code.
    const entries = ['coreProcess.ts', 'leanCoreEntry.ts', 'core/main.ts', 'services/inline.ts', 'leanEntry.ts', 'masterProcess.ts', 'serviceProcess.ts',
      ...sources('services').filter((file) => /Process\.ts$/.test(file) && !isSwarmCode(file))]
    for (const entry of entries) expect([...closureOf(entry).keys()].filter(isSwarmCode), entry).toEqual([])
    // The Swarm's own entries do reach it: the walk passes over a door, and only a door.
    expect([...closureOf('superTabs/inServices.ts').keys()].filter(isSwarmCode).length).toBeGreaterThan(5)
  }, WALK_TIMEOUT_MS)

  it('live transcript coordination depends on engine contracts, with neutral folding mechanics', () => {
    const owners = new Set(['core/transcripts/attach.ts', 'core/transcripts/ingest.ts', 'core/transcripts/normalizers.ts'])
    const wrong = importsIn('core').filter(({ file, from, typeOnly }) => owners.has(file) && !typeOnly
      && (/engines\/(claude|codex)\//.test(from) || /lib\/normalize\.js$/.test(from) || /engines\/live\.js$/.test(from)))
    expect(wrong, 'Inject the live facet; do not construct or edit an engine parser in core.').toEqual([])
    for (const entry of ['lib/attachTranscript.ts', 'engines/kit/events.ts', 'engines/kit/transcriptFold.ts']) {
      expect([...closureOf(entry).keys()].filter(file => /^engines\/(claude|codex)\//.test(file)), entry).toEqual([])
    }
  })

  it('runtime profile authority and wire values load contracts without vendor profile implementations', () => {
    for (const entry of ['core/engines/runtimeSessions.ts', 'core/engines/runtimeProfiles.ts',
      'core/engines/runtimeTransport.ts', 'lib/runtimeProfileWire.ts', 'lib/runtimeProfileState.ts']) {
      expect([...closureOf(entry).keys()].filter(file => /^engines\/(claude|codex)\//.test(file)), entry).toEqual([])
      expect(closureOf(entry).has('lib/runtimeProfile.ts'), entry).toBe(false)
    }
  })

  it('screen, submission and native-control brokers and input authority do not load the engines\' native code', () => {
    for (const entry of ['core/input.ts', 'core/questions.ts', 'core/engines/screens.ts', 'core/engines/screenTransport.ts',
      'core/deviceInput.ts', 'lib/sessionInput.ts', 'core/engines/submissions.ts', 'core/engines/submissionTransport.ts',
      'core/engines/nativeControls.ts', 'core/turns/activity.ts']) {
      expect([...closureOf(entry).keys()].filter(file => /^engines\/(claude|codex)\//.test(file)), entry).toEqual([])
    }
  })

  it('hook installation, admission, transcript correction and turn closing load the engines\' declared hook contracts alone', () => {
    const contracts = new Set(['engines/claude/hookContract.ts', 'engines/codex/hookContract.ts'])
    for (const entry of ['engines/hooks.ts', 'engines/kit/hookSettings.ts', 'engines/kit/hookRules.ts', 'engines/kit/stopHook.ts',
      'core/turns/turnHooks.ts']) {
      expect([...closureOf(entry).keys()].filter(file => /^engines\/(claude|codex)\//.test(file) && !contracts.has(file)), entry).toEqual([])
    }
    expect([...closureOf('engines/hooks.ts').keys()].filter(file => contracts.has(file)).sort()).toEqual([...contracts].sort())
  })

  it('discovery loads the engines\' declared contracts alone', () => {
    // The pass and what it reads off a process, the grid's model, the start-up repair, and the registry.
    for (const entry of ['lib/tmux.ts', 'lib/terminalAgentDiscovery.ts', 'lib/gridAssignment.ts', 'lib/cwdRepair.ts', 'lib/registry.ts',
      'engines/discoveries.ts', 'engines/kit/processFacts.ts', 'engines/kit/projectFolder.ts']) {
      expect([...closureOf(entry).keys()].filter(file => /^engines\/(claude|codex)\//.test(file) && !DECLARED.has(file) && !LAUNCH_CONTRACTS.has(file)), entry).toEqual([])
    }
    expect([...closureOf('engines/discoveries.ts').keys()].filter(file => /^engines\/(claude|codex)\//.test(file)).sort())
      .toEqual(['engines/claude/discoveryContract.ts', 'engines/codex/discoveryContract.ts'])
  })

  it('the registry\'s load, session repair, resume capture and the handoff load the engines\' declared session stores alone', () => {
    // Binding a session, finding it by its id, by its process or by a scan, and putting back a parent's: session
    // control, with no engine worker and none of the two engines' code (docs/design/2026-10-08-engine-launch.md, (c4)).
    const theirs = (entry: string): string[] => [...closureOf(entry).keys()]
      .filter(file => /^engines\/(claude|codex)\//.test(file) && !DECLARED.has(file) && !LAUNCH_CONTRACTS.has(file))
    // Pi's session reader, which session repair names Pi's folders with, streams lines (lib/transcriptLines.ts) and no
    // longer loads the readers of the two engines' transcripts ((c5)).
    for (const entry of ['lib/registry.ts', 'lib/handoffDiscovery.ts', 'lib/engineHomes.ts', 'engines/sessionFiles.ts',
      'engines/sessionStoreContracts.ts', 'engines/kit/sessionRecords.ts', 'engines/kit/continuation.ts',
      'lib/sessionRepair.ts', 'lib/captureResumeIdentity.ts', 'engines/sessionStores.ts', 'core/agents/bind.ts']) {
      expect(theirs(entry), entry).toEqual([])
    }
    // The stores alone, and what Codex's shares with its launch and hook contracts (the rollout layout, the child rule).
    expect([...closureOf('engines/sessionStoreContracts.ts').keys()].filter(file => /^engines\/(claude|codex)\//.test(file)).sort())
      .toEqual(['engines/claude/sessionStore.ts', 'engines/codex/hookContract.ts', 'engines/codex/launch.ts', 'engines/codex/sessionStore.ts'])
    // The kit's mechanics know no engine at all.
    for (const entry of ['engines/kit/sessionRecords.ts', 'engines/kit/continuation.ts']) {
      expect([...closureOf(entry).keys()].filter(file => /^engines\/(claude|codex)\//.test(file)), entry).toEqual([])
    }
  })

  it('adoption, activity, pages, history and the last turn load the engines\' declarations alone, never their normalizers', () => {
    // Which conversations are on this machine and which process holds one (taking one over stops that process),
    // an agent's latest activity, a thread's pages and line count, and core's history and recap reads
    // (docs/design/2026-10-08-engine-launch.md, (c5)). Their replays are their readers', in their workers.
    const adoption = new Set(['engines/claude/adoption.ts', 'engines/codex/adoption.ts'])
    const declared = new Set([...DECLARED, ...LAUNCH_CONTRACTS, ...adoption])
    const theirs = (entry: string): string[] => [...closureOf(entry).keys()].filter(file => /^engines\/(claude|codex)\//.test(file) && !declared.has(file))
    for (const entry of ['engines/adoptions.ts', 'engines/kit/adoption.ts', 'lib/transcriptActivity.ts', 'lib/transcriptPages.ts',
      'lib/transcriptLines.ts', 'core/transcripts/history.ts', 'core/transcripts/lastTurn.ts', 'lib/agentFrame.ts',
      'lib/sessionSearch/external.ts']) {
      expect(theirs(entry), entry).toEqual([])
    }
    // Adoption's composition reads the two declarations (and, through the process table, the discovery contracts).
    expect([...closureOf('engines/adoptions.ts').keys()].filter(file => adoption.has(file)).sort()).toEqual([...adoption].sort())
    // The pager, the line streamer and the paged history know no engine at all: each engine's reader hands the pager
    // its rules. The kit's adoption names none either; it reads the process table (lib/tmux.ts) to match an owner.
    for (const entry of ['lib/transcriptPages.ts', 'lib/transcriptLines.ts', 'engines/kit/history.ts']) {
      expect([...closureOf(entry).keys()].filter(file => /^engines\/(?!kit\/|facets\/|types\.ts$)/.test(file)), entry).toEqual([])
    }
    expect(parsedFile(join(SRC, 'engines/kit/adoption.ts')).imports.map(path => relative(SRC, path)).filter(file => /^engines\/(?!kit\/|facets\/)/.test(file))).toEqual([])
    // Core's adoption reaches none of the two engines' code: Devin's reader, which replays its store with Claude
    // Code's normalizer, is loaded with Devin's code ((o5)).
    expect(theirs('lib/sessionSearch/externals/index.ts')).toEqual([])
  })

  it('building a launch loads the engines\' declared launch contracts alone', () => {
    const contracts = new Set(['engines/claude/launch.ts', 'engines/codex/launch.ts'])
    // The builders: the argv and its script, a relaunch's overrides, a harness's flags. The homes they launch in
    // are read with the session stores' declarations (lib/engineHomes.ts), data as well.
    for (const entry of ['lib/engineLaunch.ts', 'lib/launchOverrides.ts', 'engines/launches.ts', 'engines/kit/launchArgs.ts',
      'engines/kit/launchStartup.ts', 'dsh/adapters.ts', 'engines/launchPrep.ts', 'engines/kit/folderTrust.ts',
      'engines/kit/resumeRepair.ts', 'dsh/runtime.ts', 'lib/apiInstructions.ts', 'engines/kit/attribution.ts', 'lib/agentAttribution.ts']) {
      expect([...closureOf(entry).keys()].filter(file => /^engines\/(claude|codex)\//.test(file) && !contracts.has(file)
        && !SESSION_STORES.has(file) && file !== 'engines/codex/hookContract.ts'), entry).toEqual([])
    }
    expect([...closureOf('lib/engineLaunch.ts').keys()].filter(file => contracts.has(file)).sort()).toEqual([...contracts].sort())
    // The launches themselves reach the registry too, whose hook admission reads the hook contracts and whose
    // load-time repair reads the declared session stores. Nothing else of the two.
    const declared = new Set([...contracts, ...DECLARED])
    for (const entry of ['core/agents/create.ts', 'core/agents/fork.ts', 'core/agents/restart.ts', 'core/agents/swap.ts',
      'core/agents/launch.ts', 'core/agents/launches.ts', 'lib/resumeAgentService.ts']) {
      expect([...closureOf(entry).keys()].filter(file => /^engines\/(claude|codex)\//.test(file) && !declared.has(file)), entry).toEqual([])
    }
  })

  it('the core loads the other engines\' code only through engines/inProcess.ts, but for the files still listed', () => {
    const closure = closureOf('core/main.ts')
    const reached = [...closure.keys()].filter(theirs).sort()
    expect(reached.filter((file) => !OTHER_ENGINES_CORE_MAY_REACH[file]), 'Load their code through engines/inProcess.ts (loadEngine), or declare what the core needs of it in engines/<name>/contract.ts.').toEqual([])
    expect(Object.keys(OTHER_ENGINES_CORE_MAY_REACH).filter((file) => !closure.has(file)), 'No longer loaded by the core: remove it from OTHER_ENGINES_CORE_MAY_REACH').toEqual([])
    for (const [entry, batch] of FACETS_FREE_OF_THEM) {
      expect([...closureOf(entry).keys()].filter(theirs), `${entry}, free of their code since ${batch}`).toEqual([])
    }
    // Native installation is eager, composed from declarations; the legacy entry is only an alias.
    expect(closureOf('core/engines/hooks.ts').has('lib/hooks.ts')).toBe(false)
    // What an engine declares is data the kit reads: its own walk reaches the kit, the engines' types and the
    // environment, and nothing of any engine's code.
    const contracts = [...closure.keys()].filter((file) => /^engines\/\w+\/contract\.ts$/.test(file))
    expect(contracts.length).toBeGreaterThan(0)
    const environment = new Set(closureOf('config/env.ts').keys())
    for (const contract of contracts) {
      expect([...closureOf(contract).keys()].filter((file) => file !== contract && !environment.has(file) && !/^engines\/(kit\/|types\.ts$)/.test(file)), contract).toEqual([])
    }
  }, WALK_TIMEOUT_MS)

  it('transcript location, native process evidence and profile discovery have no lazy implementation dependency', () => {
    for (const entry of ['core/agents/bind.ts', 'core/engines/cursorDiscovery.ts', 'engines/identities.ts',
      'engines/kit/sessionLocation.ts', 'engines/kit/transcriptDiscovery.ts', 'lib/terminalAgentDiscovery.ts', 'lib/sqliteRead.ts',
      'lib/sessionRepair.ts', 'engines/repairIdentities.ts', 'engines/kit/sessionIdentity.ts']) {
      const imports = importsFor(entry, readFileSync(join(SRC, entry), 'utf8'))
      expect(imports.filter(one => one.dynamic || /inProcess\.js$/.test(one.from)), entry).toEqual([])
    }
  })

  it('native hook installation never loads optional code and reaches only engine declarations', () => {
    for (const entry of ['core/engines/hooks.ts', 'engines/nativeHooks.ts', 'engines/kit/nativeHookSettings.ts',
      'engines/kit/nativeHookYaml.ts', 'engines/kit/nativeHookHomes.ts', 'engines/kit/nativePlugin.ts']) {
      const imports = importsFor(entry, readFileSync(join(SRC, entry), 'utf8'))
      expect(imports.filter(one => one.dynamic || /inProcess\.js$/.test(one.from)), entry).toEqual([])
      expect([...closureOf(entry).keys()].filter(theirs), entry).toEqual([])
    }
  })

  it('native launch control is eager and reaches only engine declarations', () => {
    for (const entry of ['core/agents/create.ts', 'core/agents/fork.ts', 'core/agents/retarget.ts',
      'core/agents/launch.ts', 'core/agents/launches.ts', 'core/agents/externalPreflight.ts',
      'lib/launchOverrides.ts', 'engines/launchControl.ts', 'engines/kit/nativeVersion.ts', 'engines/kit/nativeSessionModel.ts']) {
      const imports = importsFor(entry, readFileSync(join(SRC, entry), 'utf8'))
      expect(imports.filter(one => one.dynamic || /inProcess\.js$/.test(one.from)), entry).toEqual([])
    }
    expect([...closureOf('engines/launchControl.ts').keys()].filter(theirs)).toEqual([])
    for (const entry of ['engines/kit/nativeVersion.ts', 'engines/kit/nativeSessionModel.ts']) {
      expect([...closureOf(entry).keys()].filter(file => /^engines\/(?!kit\/)/.test(file)), entry).toEqual([])
    }
    const main = readFileSync(join(SRC, 'core/main.ts'), 'utf8')
    expect(main).not.toMatch(/\bengineNow\s*\(\s*['"]opencode['"]/)
  })

  it('the gateway reaches the core only through core/api.ts: never a core module, the registry, cli.ts or the socket', () => {
    // It speaks to the core through GatewayPort and GatewayEvents alone, so that it can run in a process of
    // its own (step 10, R2) without taking any of the core with it.
    const wrong = importsIn('gateway').filter(({ from, typeOnly }) => {
      if (/(^|\/)core\//.test(from)) return from !== '../core/api.js' || !typeOnly
      if (/(^|\/)(cli|backendSocket|localWsServer)\.js$/.test(from)) return true
      return /(^|\/)lib\/registry\.js$/.test(from)
    }).map(({ file, from }) => `${file} imports ${from}`)
    expect(wrong, 'The gateway is the relay, not the core: what it needs of the core is an event in GatewayEvents (src/core/api.ts).').toEqual([])
    expect(importsIn('gateway').some(({ from, typeOnly }) => from === '../core/api.js' && typeOnly)).toBe(true)
  })

  it('the local socket finds the daemon\'s Windows pipe without the daemon\'s client: no import cycle between them', () => {
    // daemonEndpoint.ts imports localSocket.ts for the socket's path; the pipe's lookup both use is lib/windows/daemonPipe.ts.
    expect(closureOf('lib/localSocket.ts').has('lib/daemonEndpoint.ts')).toBe(false)
    expect(closureOf('lib/localSocket.ts').has('lib/windows/daemonPipe.ts')).toBe(true)
  })

  it('the master holds no feature code: Node itself, its own folder, and the log trimmer', () => {
    const wrong = importsIn('harnessd').filter(({ from }) => !from.startsWith('node:') && !from.startsWith('./') && from !== '../lib/log.js')
      .map(({ file, from }) => `${file} imports ${from}`)
    expect(wrong, 'The master is the one process that must not fail: no feature code in it (src/harnessd/AGENTS.md).').toEqual([])
  })

  it('the core\'s process loads no edge file but those listed, and reports source size for review', () => {
    const closure = closureOf('core/main.ts')
    const lines = [...closure.values()].reduce((sum, count) => sum + count, 0)
    // The October 6 TUI merge exposed the problem with the old line caps: a safe shell-return fix
    // failed despite adding no dependency. Report size, but gate actual boundaries below. Runtime
    // cost belongs to e2e/perf.e2e.ts; crash and hang isolation to e2e/serviceProcesses.e2e.ts.
    console.info('[architecture] source size (informational):', JSON.stringify({
      coreClosureLines: lines,
      coreClosureFiles: closure.size,
      runForegroundLines: runForegroundLines(),
      backendSocketLines: readFileSync(join(SRC, 'backendSocket.ts'), 'utf8').split('\n').length,
    }))
    const edge = [...closure.keys()].filter((file) => EDGE.some((pattern) => pattern.test(file))).sort()
    expect(edge.filter((file) => !CORE_MAY_REACH[file]), 'The core reaches a service only through its link and manifest (core/api.ts), never its code: import it from the service, not the core.').toEqual([])
    expect(Object.keys(CORE_MAY_REACH).filter((file) => !closure.has(file)), 'No longer loaded by the core: remove it from CORE_MAY_REACH').toEqual([])
  }, WALK_TIMEOUT_MS)

  it('finds what it checks: imports of every kind, in every folder', () => {
    const services = importsIn('services')
    expect(services.some(({ from, typeOnly }) => from === '../core/api.js' && typeOnly)).toBe(true)
    expect(services.some(({ from, typeOnly }) => from === '../core/api.js' && !typeOnly)).toBe(true)
    expect(importsIn('core').some(({ from, typeOnly }) => /backendSocket\.js$/.test(from) && typeOnly)).toBe(true)
    expect(importsIn('harnessd').some(({ from }) => from.startsWith('node:'))).toBe(true)
    expect(runForegroundLines()).toBeGreaterThan(0)
    // Every kind of import the closure follows, and the one it does not.
    const imports = valueImports('example.ts', [
      "import type { A } from './a.js'", "import { type B } from './b.js'", "import { C, type D } from './c.js'",
      "export { E } from './e.js'", "export type { F } from './f.js'", "import './g.js'",
      "const h = async () => import('./h.js')", "import { readFileSync } from 'node:fs'",
    ].join('\n'))
    expect(imports).toEqual(['./c.js', './e.js', './g.js', './h.js'])
    // The bundle's entry reaches the CLI only through a dynamic import (entry.ts), and the core's entry its own modules.
    expect(closureOf('entry.ts').has('cli.ts')).toBe(true)
    expect(closureOf('core/main.ts').has('core/api.ts')).toBe(true)
    expect(closureOf('core/main.ts').has('cli.ts')).toBe(false)
    // The core loads the services' own code only when they run in its process: imported dynamically, and
    // only from its entry, the import is not followed. Any other import of it is.
    const main = importsFor('core/main.ts', readFileSync(join(SRC, 'core', 'main.ts'), 'utf8')).filter(({ from }) => from === '../services/inline.js')
    expect(main).toEqual([{ from: '../services/inline.js', dynamic: true }])
    expect(closureOf('core/main.ts').has(IN_PROCESS_ONLY)).toBe(false)
    expect(importsFor('example.ts', "import { startSearch } from './services/inline.js'")).toEqual([{ from: './services/inline.js', dynamic: false }])
    // The other engines' code: an `import()` of it is passed over in engines/inProcess.ts alone, and followed
    // anywhere else, as is a static import of it from the loader.
    expect(importsFor('engines/inProcess.ts', readFileSync(join(SRC, 'engines', 'inProcess.ts'), 'utf8'))).toContainEqual({ from: '../lib/legacyScreen.js', dynamic: true })
    expect(closureOf('engines/inProcess.ts').has('lib/legacyScreen.ts')).toBe(false)
    expect(followed('engines/inProcess.ts', 'lib/legacyScreen.ts', true)).toBe(false)
    expect(followed('core/main.ts', 'lib/legacyScreen.ts', true)).toBe(true)
    expect(followed('engines/inProcess.ts', 'lib/legacyScreen.ts', false)).toBe(true)
    expect(followed('core/main.ts', IN_PROCESS_ONLY, true)).toBe(false)
    for (const exception of Object.keys(SERVICE_MAY_IMPORT)) {
      const [file, from] = exception.split(' → ')
      expect(services.some((found) => found.file === file && found.from === from), `${exception} is no longer needed: remove it`).toBe(true)
    }
  }, WALK_TIMEOUT_MS)
})