@volter/world-runtime 2.0.0

package/dist/src/root.js

@@ -0,0 +1,312 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+// A TWIN'S ROOT (docs/concepts/the-model.md): the vendor's real account
+// behind a twin on a shared world. `volter twin <vendor> root <url> --deploy <policy>` records it,
+// key-free, in `.volter/world.json` (committed) and, at boot, in the twin's state dir (core's
+// root.json — where the write path reads it). `volter twin <vendor> credential` seals the vendor's
+// credential beside the world under `.volter/credentials/<vendor>.json`, envelope-encrypted with
+// a key that lives in the user's config directory and nowhere else (rule 5: never in the repo,
+// never in a pack, never an env var). `volter world deploy` performs landed entries against each
+// root through the pack's adapters over the kernel executor, with the world's checks in front;
+// `deploy: auto` does the same the moment an entry is appended (the host installs the hook).
+import { packEntry } from "./catalog.js";
+import { existsSync, readdirSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { authStrategyFor, getActiveWorldStore, getPack, sealingKey, buildRemoteExecute, clearRoot, openSealedCredential, readRoot, registerStateSystem, sealCredential, stateDirName, stateSystemFor, validateRemoteOrigin, writeRoot, } from '@volter/world-core';
+import { loadWorldConfig, writeWorldConfig } from "./configs.js";
+import { changesetReadiness, collectObservations, foldObservations, loadChecks, openRootCredential, performEntries, rootCustody, protocolStanding } from '@volter/world-core';
+import { findWorldChangeset, listWorldChangesets } from "./changeset.js";
+import { statusWorld } from "./runtime.js";
+import { findInstalledPackage, twinPackageName } from "./catalog.js";
+// ── the user's sealing key ──────────────────────────────────────────────────────────────────
+/** `$XDG_CONFIG_HOME/volter/kek`, else `~/.config/volter/kek`: the key every credential this user
+ *  seals is wrapped under. Made on first use, 0600, never printed. */
+export { userKek, userKekPath } from '@volter/world-core';
+// ── the sealed credential, beside the world ─────────────────────────────────────────────────
+export function credentialPath(worldRoot, vendor) {
+    return join(resolve(worldRoot), stateDirName(), 'credentials', `${vendor}.json`);
+}
+export async function sealTwinCredential(worldRoot, vendor, payload, at = new Date().toISOString()) {
+    const sealed = await sealCredential(sealingKey(), payload, at, vendor);
+    getActiveWorldStore().write(credentialPath(worldRoot, vendor), `${JSON.stringify(sealed, null, 2)}\n`, { secret: true });
+    return { placedAt: sealed.placedAt, fingerprint: sealed.fingerprint };
+}
+export function sealedCredentialInfo(worldRoot, vendor) {
+    const text = getActiveWorldStore().read(credentialPath(worldRoot, vendor));
+    if (text === null)
+        return null;
+    const sealed = JSON.parse(text);
+    return { placedAt: sealed.placedAt, fingerprint: sealed.fingerprint };
+}
+/** The signing secret sealed beside the credential (`{ headers, signingSecret }`), for ingest; null when none. */
+export async function twinSigningSecret(worldRoot, vendor) {
+    const text = getActiveWorldStore().read(credentialPath(worldRoot, vendor));
+    if (text === null)
+        return null;
+    const payload = await openSealedCredential(sealingKey(), JSON.parse(text), vendor);
+    return typeof payload.signingSecret === 'string' && payload.signingSecret.length >= 8 ? payload.signingSecret : null;
+}
+/** A bare token becomes the vendor's own header. A JSON object is taken as the payload. */
+export function credentialPayloadFrom(input, vendor) {
+    const text = input.trim();
+    if (text.startsWith('{'))
+        return JSON.parse(text);
+    const header = HEADER_BY_VENDOR[vendor] ?? ((token) => ({ authorization: `Bearer ${token}` }));
+    return { headers: header(text) };
+}
+const HEADER_BY_VENDOR = {
+    jira: (token) => ({ authorization: `Basic ${Buffer.from(`agent@acme.example:${token}`).toString('base64')}` }),
+    openai: (token) => ({ authorization: `Bearer ${token}` }),
+};
+export function setTwinRoot(worldRoot, vendor, config, opts = {}) {
+    const { path, config: world } = loadWorldConfig(opts.config ?? defaultConfigPath(worldRoot), worldRoot);
+    const service = world.services.find((s) => s.id === vendor);
+    if (!service)
+        throw new Error(`no twin "${vendor}" in ${path}`);
+    if (config) {
+        validateRemoteOrigin(config.url, { allowInsecureLoopback: true });
+        service.root = config;
+    }
+    else
+        delete service.root;
+    writeWorldConfig(path, world);
+    return { path };
+}
+function defaultConfigPath(worldRoot) {
+    const inRepo = join(resolve(worldRoot), stateDirName(), 'world.json');
+    return getActiveWorldStore().exists(inRepo) ? inRepo : 'world';
+}
+/** Every state service dir under a twin's control root (its own id first, then what it recorded under). */
+function stateDirsOf(controlRoot) {
+    const stateRoot = join(controlRoot, stateDirName(), 'world');
+    const store = getActiveWorldStore();
+    return store.list(stateRoot).filter((name) => store.stat(join(stateRoot, name))?.isDirectory).sort();
+}
+/** At boot: every twin with a root gets root.json in its state dir(s), so core's write path and the
+ *  deploy read it there; a twin whose root was cleared loses it. */
+export function materializeRoots(config, dataDir, worldRoot) {
+    for (const service of config.services) {
+        if (service.type === 'external')
+            continue; // a root belongs to a service the world owns
+        const controlRoot = join(dataDir, service.id);
+        const root = service.root;
+        const states = new Set([service.id, ...stateDirsOf(controlRoot)]);
+        for (const state of states) {
+            if (root)
+                writeRoot(state, { ...root, credential: credentialPath(worldRoot, service.id) }, controlRoot);
+            else
+                clearRoot(state, controlRoot);
+        }
+    }
+}
+/** The root a state service under `controlRoot` is bound to — its own root.json, else a sibling
+ *  state's (slack records under `chat`; the root was written under `slack`). */
+export function rootForControlRoot(controlRoot, service) {
+    const own = readRoot(service, controlRoot);
+    if (own)
+        return own;
+    for (const state of stateDirsOf(controlRoot)) {
+        const r = readRoot(state, controlRoot);
+        if (r)
+            return r;
+    }
+    return null;
+}
+// ── the pack's adapters ─────────────────────────────────────────────────────────────────────
+async function packModule(vendor, from) {
+    // a host that registered its packs (a hosted World bundles the catalog) resolves without importing
+    const registered = getPack(vendor);
+    if (registered)
+        return { pack: registered };
+    const entry = packEntryPath(vendor, from);
+    return entry ? (await import(__rewriteRelativeImportExtension(entry))) : null;
+}
+/** The pack's module itself, installed beside the World or in this checkout: its every export (a
+ *  mirror's shell and client), where the registry holds only the descriptor. */
+function packEntryPath(vendor, from) {
+    const installed = findInstalledPackage(from, twinPackageName(vendor));
+    if (installed)
+        return packEntry(installed);
+    const checkout = resolve(import.meta.dir, '..', '..', 'twin', vendor, 'src', 'index.ts');
+    return existsSync(checkout) ? checkout : null;
+}
+/** The pack's mirror module (`src/<vendor>-mirror-ui.ts`: its shell, client and stylesheet), read as the
+ *  hosted mirror build reads it (apps/cloud/scripts/mirrors.ts); a pack's index need not re-export them. */
+export async function packMirrorExports(vendor, from) {
+    const entry = packEntryPath(vendor, from);
+    if (!entry)
+        return null;
+    const dir = dirname(entry);
+    const file = existsSync(dir) ? readdirSync(dir).find((f) => /-mirror-ui\.(ts|js)$/.test(f) && !f.includes('.test.')) : undefined;
+    return (await import(__rewriteRelativeImportExtension(file ? join(dir, file) : entry)));
+}
+export async function adaptersFor(vendor, from) {
+    const registered = stateSystemFor(vendor);
+    // a registration is the whole state system for that twin (a stub in a test, a pack's own
+    // descriptor); only an unregistered twin is resolved from the pack's anchored exports
+    if (registered)
+        return registered;
+    const mod = await packModule(vendor, from);
+    if (!mod)
+        return {};
+    const pack = mod.pack;
+    if (pack?.stateSystem?.perform) {
+        registerStateSystem(vendor, pack.stateSystem);
+        return pack.stateSystem;
+    }
+    // a protocol 2 pack NAMES its adapters (docs/contributing/architecture.md#protocol-2-the-pack-is-a-plugin); only a protocol 1
+    // pack is resolved from its anchored exports
+    if (protocolStanding(pack?.protocol).major >= 2)
+        throw new Error(`the ${vendor} pack declares protocol 2 but names no adapters — \`stateSystem: { perform, refresh?, ingest? }\` on its descriptor`);
+    const name = (re) => Object.keys(mod).find((k) => re.test(k) && typeof mod[k] === 'function');
+    const performName = name(/^perform\w+Action$/);
+    const refreshName = name(/^refresh\w+$/) ?? name(/^sync\w+FromRemote$/);
+    const ingestName = name(/^ingest\w+Event$/);
+    const out = { ...(performName ? { perform: mod[performName] } : {}), ...(refreshName ? { refresh: mod[refreshName] } : {}), ...(ingestName ? { ingest: mod[ingestName] } : {}) };
+    if (out.perform)
+        registerStateSystem(vendor, out);
+    return out;
+}
+// ── the world's checks ──────────────────────────────────────────────────────────────────────
+/** `.volter/checks/*.ts|js`: each exports `check` (or default) as `{ name, run }`. The shipped
+ *  no-secrets check runs first, always. */
+export const loadWorldChecks = loadChecks;
+/** The pack's declared refresh posture, read from its descriptor. */
+export async function refreshPosture(vendor, from) {
+    const mod = await packModule(vendor, from);
+    return mod?.pack?.refresh;
+}
+/** `<N>(s|m|h|d)` as milliseconds, or null when malformed. */
+export function spanMs(text) {
+    const m = /^(\d+(?:\.\d+)?)(s|m|h|d)$/.exec(text.trim());
+    return m ? Number(m[1]) * { s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000 }[m[2]] : null;
+}
+/** PERFORM a twin's waiting entries against its root: the kernel's head (`performEntries`) with the
+ *  pack's adapters and the world's checks. A refresh first, when the pack has one, so a deploy sees
+ *  the vendor as it stands. */
+export async function deployTwin(opts) {
+    const adapters = await adaptersFor(opts.vendor, opts.worldRoot);
+    if (!adapters.perform)
+        throw new Error(`the ${opts.vendor} twin has no perform adapter — it cannot deploy to a vendor yet`);
+    let refreshed = false;
+    // a refresh first, best effort: the vendor being unreachable is what the PERFORM records as `failed`
+    if (adapters.refresh) {
+        try {
+            const r = await refreshTwin({ ...opts, force: true });
+            refreshed = r.refreshed;
+        }
+        catch {
+            refreshed = false;
+        }
+    }
+    const report = await performEntries({ service: opts.state, root: opts.controlRoot, adapters, checks: opts.checks ?? (await loadChecks(opts.worldRoot)), ...(opts.actionIds ? { actionIds: opts.actionIds } : {}), ...(opts.at ? { at: opts.at } : {}) });
+    return { service: opts.vendor, state: opts.state, refreshed, report };
+}
+/** REFRESH one twin from its root: the pack's refresh adapter over the executor observes resources;
+ *  the kernel folds them onto the root's log (company contract "Refresh is the kernel's fold"). On
+ *  demand it is throttled by the root's `refresh.atMost`, else the pack's `onDemand.atMost`. */
+export async function refreshTwin(opts) {
+    const origin = validateRemoteOrigin(opts.root.url, { allowInsecureLoopback: true });
+    const adapters = await adaptersFor(opts.vendor, opts.worldRoot);
+    // the sealed credential's keyed fingerprint, as a perform's context carries it: a pack keys its budget by it
+    const credentialFingerprint = sealedCredentialInfo(opts.worldRoot, opts.vendor)?.fingerprint;
+    if (!adapters.refresh)
+        return { refreshed: false, reason: `the ${opts.vendor} twin has no refresh adapter` };
+    const marker = join(opts.controlRoot, stateDirName(), 'world', opts.vendor, 'refresh.json');
+    const atMost = opts.root.refresh?.atMost ?? (await refreshPosture(opts.vendor, opts.worldRoot))?.onDemand?.atMost;
+    if (!opts.force && atMost) {
+        const span = spanMs(atMost);
+        const held = getActiveWorldStore().read(marker);
+        const last = held !== null ? JSON.parse(held).at : undefined;
+        if (span !== null && last && Date.now() - Date.parse(last) < span)
+            return { refreshed: false, reason: `refreshed at ${last}; the ${opts.vendor} twin refreshes at most every ${atMost} (--force to refresh now)` };
+    }
+    const credential = await openRootCredential(opts.root, opts.vendor);
+    const adapterOrigin = opts.root.scope ? `${origin.href.replace(/\/+$/, '')}/${opts.root.scope.replace(/^\/+/, '')}` : origin.href;
+    const at = new Date().toISOString();
+    const store = getActiveWorldStore();
+    let value;
+    let observations;
+    try {
+        ({ value, observations } = await collectObservations(() => adapters.refresh(buildRemoteExecute(origin, credential, authStrategyFor(opts.vendor), getPack(opts.vendor)?.hosts, { custody: rootCustody(opts.root, opts.vendor) }), { root: opts.controlRoot, origin: adapterOrigin, ...(credentialFingerprint ? { credential: credentialFingerprint } : {}) })));
+    }
+    catch (error) {
+        // the vendor was asked and did not answer: the marker keeps the last fold's numbers and records the
+        // failure — its reason and how many in a row — so the status door and the twin's status say so
+        const held = store.read(marker);
+        const previous = held !== null ? JSON.parse(held) : {};
+        const reason = error instanceof Error ? error.message : String(error);
+        store.write(marker, `${JSON.stringify({ ...previous, at: new Date().toISOString(), failed: { at, reason, count: (previous.failed?.count ?? 0) + 1 } })}\n`);
+        throw error;
+    }
+    const complete = value?.complete;
+    const report = foldObservations(observations, { root: opts.controlRoot, at, ...(complete ? { complete } : {}) });
+    // the marker says when the vendor was LAST asked — the refresh's end, so `atMost` counts from there;
+    // a fold that completes clears any recorded failure
+    store.write(marker, `${JSON.stringify({ at: new Date().toISOString(), observedAt: at, ...report })}\n`);
+    return { refreshed: true, report };
+}
+/** DEPLOY a world: perform landed entries against each root twin's vendor, by policy. A named
+ *  changeset deploys its entries (a gated root needs it verified and approved); no name deploys
+ *  everything deployable — under `gated`, the entries of every ready changeset. */
+export async function deployWorld(name, opts = {}) {
+    const worldRoot = resolve(opts.root ?? process.cwd());
+    const inst = opts.instance ?? statusWorld(name, worldRoot);
+    const out = [];
+    if (!opts.changeset) {
+        // no name: every ready changeset, by name, in order — so each outcome says which it was for
+        const ready = listWorldChangesets({ root: worldRoot, world: name }).filter((l) => changesetReadiness(l.changeset).ready && !l.changeset.actions.every((e) => { const r = rootForControlRoot(join(inst.dirs.data, e.service), e.service); return r === null; })).sort((a, b) => a.changeset.createdAt.localeCompare(b.changeset.createdAt));
+        const anyGated = Object.keys(inst.services).some((s) => rootForControlRoot(join(inst.dirs.data, s), s)?.deploy === 'gated');
+        if (anyGated || ready.length) {
+            for (const l of ready)
+                out.push(...(await deployWorld(name, { ...opts, changeset: l.changeset.name })).map((o) => ({ ...o, changeset: l.changeset.name })));
+            if (anyGated)
+                return out;
+        }
+    }
+    const located = opts.changeset ? [findWorldChangeset(opts.changeset, { root: worldRoot, world: name })] : listWorldChangesets({ root: worldRoot, world: name });
+    const ready = new Map();
+    for (const l of located) {
+        const readiness = changesetReadiness(l.changeset);
+        if (!readiness.ready) {
+            const gated = [...new Set(l.changeset.actions.map((e) => e.service))].some((s) => rootForControlRoot(join(inst.dirs.data, s), s)?.deploy === 'gated');
+            if (opts.changeset && gated)
+                throw new Error(`changeset ${opts.changeset} is not ready: ${readiness.reasons.join('; ')}`);
+            if (!opts.changeset)
+                continue;
+        }
+        for (const e of l.changeset.actions)
+            ready.set(e.service, [...(ready.get(e.service) ?? []), e.action.id]);
+    }
+    const checks = opts.checks ?? (await loadWorldChecks(worldRoot));
+    for (const service of Object.keys(inst.services).sort()) {
+        const controlRoot = join(inst.dirs.data, service);
+        const root = rootForControlRoot(controlRoot, service);
+        if (!root)
+            continue;
+        for (const state of new Set([service, ...stateDirsOf(controlRoot)])) {
+            if (!getActiveWorldStore().exists(join(controlRoot, stateDirName(), 'world', state, 'actions.jsonl')))
+                continue;
+            const ids = root.deploy === 'gated' || opts.changeset ? ready.get(service) : undefined;
+            if ((root.deploy === 'gated' || opts.changeset) && (!ids || ids.length === 0))
+                continue;
+            out.push(await deployTwin({ worldRoot, vendor: service, controlRoot, state, root, checks, ...(ids ? { actionIds: ids } : {}) }));
+        }
+    }
+    // a named changeset that performed nothing says why, rather than reading as a quiet success
+    if (opts.changeset && out.length === 0) {
+        const unrooted = [...ready.keys()].filter((service) => !rootForControlRoot(join(inst.dirs.data, service), service));
+        if (unrooted.length)
+            throw new Error(`changeset ${opts.changeset} has nothing to perform: ${unrooted.join(', ')} ${unrooted.length === 1 ? 'has' : 'have'} no root on this world (\`volter twin <vendor> root <url>\`)`);
+    }
+    return out;
+}
+// ── deploy: auto ────────────────────────────────────────────────────────────────────────────
+// The auto-deploy hook is GONE (2026-09-06): the kernel's head performs an `auto` write in the
+// process that serves the twin (core head.ts), and the push door performs what it lands.

package/dist/src/run-task-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/run-task-worker.js

@@ -0,0 +1,38 @@
+import { runWorldOwned } from "./runtime.js";
+// Only this process owns the IPC endpoint; child stdio explicitly excludes fd 3. A lost
+// caller requests cancellation, including while startup is still settling. No service restarts.
+if (!process.send)
+    throw new Error('World task owner requires its private lifetime channel');
+const abort = new AbortController();
+let started = false;
+process.on('disconnect', () => {
+    abort.abort('SIGTERM');
+    if (!started)
+        process.exit(0);
+});
+// A dead caller may also close the output reader. Reporting failure must not kill cleanup.
+process.stdout.on('error', () => { });
+process.stderr.on('error', () => { });
+process.on('message', async (message) => {
+    const request = message;
+    if (request.type === 'cancel') {
+        abort.abort(request.signal);
+        return;
+    }
+    if (request.type !== 'start' || started)
+        return;
+    started = true;
+    let reply;
+    try {
+        reply = { result: await runWorldOwned(request.configId, request.command, request.options, abort.signal) };
+    }
+    catch (error) {
+        reply = { error: error instanceof Error ? error.message : String(error) };
+    }
+    if ('error' in reply)
+        process.stderr.write(`${reply.error}\n`);
+    if (process.connected)
+        process.send(reply, () => process.exit('error' in reply ? 1 : 0));
+    else
+        process.exit('error' in reply ? 1 : 0);
+});

package/dist/src/run-task.d.ts

@@ -0,0 +1,18 @@
+import type { RunWorldOptions, runWorldOwned } from './runtime.js';
+export type RunTaskRequest = {
+    type: 'start';
+    configId: string;
+    command: string[];
+    options: RunWorldOptions;
+};
+type RunTaskResult = Awaited<ReturnType<typeof runWorldOwned>>;
+export type RunTaskReply = {
+    result: RunTaskResult;
+} | {
+    error: string;
+};
+/** A task lifetime handle, not a service restarter. The private IPC descriptor is never passed
+ * to services or commands. EOF survives caller SIGKILL without relying on PID reuse or idle time.
+ * The task process is outside the caller's POSIX process group and owns boot through teardown. */
+export declare function superviseWorldRun(configId: string, command: string[], options: RunWorldOptions): Promise<RunTaskResult>;
+export {};

package/dist/src/run-task.js

@@ -0,0 +1,48 @@
+import { offSignal } from "./signals.js";
+import { spawn } from 'node:child_process';
+import { resolve } from 'node:path';
+import { siblingScript } from "./sibling.js";
+/** A task lifetime handle, not a service restarter. The private IPC descriptor is never passed
+ * to services or commands. EOF survives caller SIGKILL without relying on PID reuse or idle time.
+ * The task process is outside the caller's POSIX process group and owns boot through teardown. */
+export function superviseWorldRun(configId, command, options) {
+    return new Promise((done, reject) => {
+        const child = spawn(process.execPath, [siblingScript(import.meta.url, 'run-task-worker')], {
+            cwd: process.cwd(), env: process.env, detached: process.platform !== 'win32',
+            stdio: ['inherit', 'inherit', 'inherit', 'ipc'], serialization: 'json',
+        });
+        let reply;
+        let failure;
+        const cancel = (signal) => {
+            if (child.connected)
+                child.send({ type: 'cancel', signal }, error => { if (error)
+                    failure ??= error; });
+        };
+        const onInt = () => cancel('SIGINT');
+        const onTerm = () => cancel('SIGTERM');
+        process.on('SIGINT', onInt);
+        process.on('SIGTERM', onTerm);
+        child.on('error', error => { failure = error; });
+        child.on('message', message => { reply = message; });
+        child.once('spawn', () => {
+            const request = { type: 'start', configId, command, options: { ...options, root: resolve(options.root ?? process.cwd()) } };
+            child.send(request, error => { if (error) {
+                failure = error;
+                if (child.connected)
+                    child.disconnect();
+            } });
+        });
+        child.once('close', (code, signal) => {
+            offSignal('SIGINT', onInt);
+            offSignal('SIGTERM', onTerm);
+            if (failure)
+                reject(failure);
+            else if (reply && 'error' in reply)
+                reject(new Error(reply.error));
+            else if (reply && code === 0)
+                done(reply.result);
+            else
+                reject(new Error(`World task owner exited without a completed teardown (${signal ?? code}); inspect World status and retained logs`));
+        });
+    });
+}

package/dist/src/runtime-test-support.d.ts

@@ -0,0 +1,59 @@
+/** Test-only seam (see runtime.ts `proxyDaemonDeadlineMs`): force the daemon-poll deadline to `ms`
+ * for the duration of `fn`, then restore whatever was there before — deterministic, no sleeps. */
+export declare function withProxyDeadline<T>(ms: number, fn: () => Promise<T> | T): Promise<T>;
+/** Best-effort cleanup for the forced-timeout tests below: with the deadline forced to 0, the
+ * detached proxy-daemon child is still spawned and may go on to write `proxy.json` a little later
+ * (asynchronously, after our synchronous poll already gave up) — kill it so it doesn't linger as an
+ * orphan process once the test's tmp root is discarded. Never gates test pass/fail. */
+export declare function reapLeakedProxyDaemon(root: string, name: string): Promise<void>;
+/** A hostname under the IANA-reserved `.invalid` TLD (RFC 2606) — guaranteed to NEVER resolve, on
+ * any network, forever. Used as the "untwinned public host" below: it is unambiguously non-local
+ * (so `isLocalOrPrivateHost` never exempts it) and unambiguously not a vendor (so it is never
+ * redirected to a twin), and a real (non-strict-egress) attempt to reach it fails FAST on DNS
+ * resolution — offline and deterministic, no dependency on real internet access. */
+export declare const UNTWINNED_HOST = "definitely-untwinned.invalid";
+/** Drive a raw CONNECT through the ambient redirect proxy and collect whatever bytes come back
+ * before the socket closes (or `timeoutMs` elapses, as a safety net — a blind-tunnel attempt to an
+ * unresolvable host closes with NO data at all, so this never actually waits the full timeout). */
+export declare function connectThroughProxy(port: number, host: string, targetHost: string, targetPort?: number, timeoutMs?: number): Promise<string>;
+/** Force `opensslAvailable()` to false via its TEST-ONLY seam (see `redirect-proxy.ts`). A
+ * PATH-shim (fake `openssl` binary prepended to PATH) was tried first and does NOT reliably work
+ * here: `opensslAvailable()`'s `spawnSync('openssl', …)` call passes no explicit `env`, and this
+ * runtime resolves the executable against a PATH snapshotted at process start rather than a
+ * same-process `process.env.PATH` mutation made mid-test (verified: a fresh child process DOES
+ * see a shimmed PATH, but mutating PATH in the already-running test process does not change what
+ * THIS process's own `spawnSync` resolves) — so the deterministic, seam-based override is used. */
+export declare function withNoOpenssl(): {
+    restore: () => void;
+};
+export declare const worlds: Array<{
+    root: string;
+    name: string;
+}>;
+/**
+ * Register the teardown hook for the CALLING test file. Every file that pushes to `worlds` must
+ * call this at top level.
+ *
+ * It has to be a function call rather than a module-scope `afterEach`, and that distinction was an
+ * eight-file process leak. A hook registered while this module's body runs belongs to whichever
+ * file happened to import it FIRST; module caching means the body never runs again, so every other
+ * file got no hook at all. Each file individually looked clean — it was the first importer — and
+ * only a whole-directory run leaked, which is exactly the shape that reads as flakiness. The
+ * stray proxy daemons and tunnel stubs then held ports until unrelated HTTP tests started failing.
+ *
+ * Teardown also settles ALL worlds before reporting: the list is spliced empty up front, so a bare
+ * `for … await` loop that rejected on the first world abandoned the rest with nothing left holding
+ * a reference to them. Nothing about a world that failed to stop makes the next one less important
+ * to stop.
+ */
+export declare function useWorldCleanup(): void;
+export declare function writeRaceConfig(root: string, id: string): void;
+/** Bounded wait (no fixed sleeps) for SIGTERM'd services to actually exit after downWorld. */
+export declare function waitForWorldDown(name: string, root: string): Promise<boolean>;
+export declare function pidAlive(pid: number): boolean;
+export declare function writeSingleTwinConfig(root: string, id: string): void;
+/** Twin + a second (non-twin) service — the proxy-attempt loop tries the ambient proxy again
+ * before starting each subsequent service, so this reaches the ambient proxy regardless of
+ * whether the single/last-service re-evaluation (TWIN-64) has landed yet — kept independent of
+ * that fix so this CONNECT-level test exercises TWIN-60's wiring in isolation. */
+export declare function writeTwinPlusAppConfig(root: string, id: string): void;