@volter/world-runtime 3.0.145 → 3.0.147

package/dist/src/covers.js

@@ -994,11 +994,12 @@ export function formatCoverageReport(report) {
         lines.push(`ACKNOWLEDGED: ${report.acknowledged.length} signal(s) accepted with recorded reasons (no twin): ${report.acknowledged.map((a) => a.vendor).join(', ')}`);
     }
     if (report.excluded.length > 0)
-        lines.push(`EXCLUDED BY SELECTION: ${report.excluded.join(', ')} (not covered; no access granted).`);
+        lines.push(`EXCLUDED BY SELECTION: ${report.excluded.join(', ')} (outside automatic selection; declared service bindings are reported separately).`);
+    const detectionScope = report.excluded.length > 0 ? 'selected detected vendor' : 'detected vendor';
     lines.push(report.ok
         ? report.acknowledged.length > 0
-            ? `COVERED (with ${report.acknowledged.length} acknowledgment(s)): every other detected vendor has a twin in world ${report.world}.`
-            : `COVERED: every detected vendor has a twin in world ${report.world}.`
+            ? `COVERED (with ${report.acknowledged.length} acknowledgment(s)): every other ${detectionScope} has a twin in world ${report.world}.`
+            : `COVERED: every ${detectionScope} has a twin in world ${report.world}.`
         : `PROOF FAILED for world ${report.world}.`);
     lines.push('Static connection check only; run an app scenario to verify behavior and shared state.');
     return `${lines.join('\n')}\n`;

package/dist/src/env-output.d.ts

@@ -1,6 +1,7 @@
 type PriorOutput = {
     path: string;
     contents: string;
+    sha256?: string;
 };
 export type EnvOutputClaim = {
     path: string;

package/dist/src/env-output.js

@@ -17,7 +17,8 @@ function inspect(path) {
 /** Refuse a custody/input file before any World service or lifecycle mutation starts. */
 export function claimEnvOutput(path, backupDir, priors = [], force = false) {
     const contents = inspect(path);
-    if (contents !== undefined && !force && !priors.some((prior) => prior.path === path && Buffer.from(prior.contents).equals(contents))) {
+    if (contents !== undefined && !force && !priors.some((prior) => prior.path === path && (Buffer.from(prior.contents).equals(contents)
+        || /^[a-f0-9]{64}$/.test(prior.sha256 ?? '') && createHash('sha256').update(contents).digest('hex') === prior.sha256))) {
         throw new Error(`World refuses existing --env-out file it does not own: ${path}. Choose a new output path; never use a custody file. --force explicitly replaces a file with a private backup.`);
     }
     if (force && contents !== undefined) {

package/dist/src/init.d.ts

@@ -37,6 +37,8 @@ export type EnvDisposition =
 'faked'
 /** a credential the vendor's twin issues at boot → `$issue:<vendor>` (the twin refuses a key it did not make) */
  | 'issued'
+/** a World-owned endpoint or reserved environment name → supplied at boot, never copied from the app */
+ | 'injected'
 /** non-credential app config → the example value copied verbatim */
  | 'kept'
 /** infra connection string → points at a World-managed infrastructure service */

package/dist/src/init.js

@@ -734,7 +734,7 @@ export function planWorldInit(name, repoPath, options = {}) {
         // World-owned names: the world INJECTS these at boot from the services above. Carrying a repo's
         // stale copy would shadow the live one.
         if (/_TWIN_URL$/.test(name) || /^VOLTER_/.test(name) || worldInjected.has(name)) {
-            envRows.push({ name, disposition: 'unknown', source, reason: 'world-owned (injected at boot) — dropped from the emitted env' });
+            envRows.push({ name, disposition: 'injected', source, reason: 'world-owned (injected at boot) — dropped from the emitted env' });
             continue;
         }
         // The application's own origin (its base URL, its auth library's URL): only the booter knows where the app is
@@ -1319,7 +1319,7 @@ export function formatInitReport(result) {
     lines.push('');
     const counts = (disposition) => plan.envRows.filter((row) => row.disposition === disposition);
     lines.push(`Env (${plan.envRows.length} name(s) from ${plan.envSources.join(', ') || 'no example env file'}):`);
-    for (const disposition of ['faked', 'kept', 'app-origin', 'stand-in', 'compose', 'placeholder', 'unknown']) {
+    for (const disposition of ['faked', 'issued', 'injected', 'kept', 'app-origin', 'stand-in', 'compose', 'placeholder', 'unknown']) {
         const rows = counts(disposition);
         if (rows.length === 0)
             continue;

package/dist/src/runtime.js

@@ -669,8 +669,8 @@ function readWorldBootRecordLocked(name, root) {
         }
         if (!Array.isArray(record.bootServices) || record.bootServices.some(id => typeof id !== 'string')
             || new Set(record.bootServices).size !== record.bootServices.length
-            || record.bootServices.length !== Object.keys(record.services).length
-            || record.bootServices.some(id => !Object.hasOwn(record.services, id)))
+            || Object.keys(record.services).some(id => !record.bootServices.includes(id))
+            || !stopped && record.bootServices.length !== Object.keys(record.services).length)
             throw new Error();
         for (const [id, service] of Object.entries(record.services)) {
             if (!service || service.id !== id || !Array.isArray(service.command) || typeof service.type !== 'string')
@@ -695,7 +695,7 @@ function readWorldBootRecordLocked(name, root) {
         return record;
     }
     catch {
-        throw new Error(`World boot record is incomplete or invalid: ${path}`);
+        throw new Error(`World boot record is incomplete or invalid: ${path}\nFrom the app directory, inspect: volter-world doctor ${name} --root .\nComplete teardown with the owning runtime: volter-world down ${name} --root .\nRetain the startup diagnostics and any history. Only a disposable instance with no state to keep may be removed with down --purge; resume never discards it automatically.`);
     }
 }
 export function admittedEnv(strip, env = process.env) {
@@ -2043,7 +2043,9 @@ export async function upWorld(configId, options = {}, abort) {
             return [];
         try {
             const prior = JSON.parse(readFileSync(file, 'utf8'));
-            return prior?.name === world && resolve(prior.root) === root ? [{ path: resolve(prior.envFile), contents: envFileContents(prior.env) }] : [];
+            return prior?.name === world && resolve(prior.root) === root ? [{ path: resolve(prior.envFile), contents: envFileContents(prior.env),
+                    ...(prior.previousEnvOutput?.path === resolve(prior.envFile) ? { sha256: prior.previousEnvOutput.sha256 } : {}),
+                }] : [];
         }
         catch {
             return [];
@@ -2248,6 +2250,7 @@ export async function upWorld(configId, options = {}, abort) {
         const worldInstance = {
             name, instance: instanceToken, config: loaded.config.id, configPath: loaded.path, root, createdAt, mode,
             dirs: { instance, logs, data }, services, env, envFile, pidsFile,
+            ...(envOutputClaim.contents === undefined ? {} : { previousEnvOutput: { path: envFile, sha256: createHash('sha256').update(envOutputClaim.contents).digest('hex') } }),
             networkCeiling: env[WORLD_NETWORK_POLICY_ENV] === undefined ? 'unrestricted' : networkPermission(parseWorldNetworkPolicy(JSON.parse(env[WORLD_NETWORK_POLICY_ENV]))),
             bootServices: loaded.config.services.map(service => service.id), bootOwner: options.owner ?? null,
             ...(loaded.config.selection ? { selection: loaded.config.selection } : {}),
@@ -2416,7 +2419,12 @@ export async function upWorld(configId, options = {}, abort) {
             mkdirSync(dirname(envFile), { recursive: true });
             // Config env and discovered credentials: a file this writes is owner-only; a file the caller already made keeps
             // the mode the caller chose (a shared env file may be read under another uid).
+            // Persist final environment identity while the claimed old output is still recoverable; caller loss between
+            // this record and publication must not make the old file appear to be custody.
+            saveWorldInstance(worldInstance);
             publishEnvOutput(envOutputClaim, envFileContents(env));
+            delete worldInstance.previousEnvOutput;
+            saveWorldInstance(worldInstance);
             boot.progress(`environment written: ${envFile}`);
             materializeBrowserFiles(data, root, name, loaded.config.id);
             writePidsFromInstance(worldInstance, Object.values(worldInstance.services).map((service) => service.pid).filter((pid) => pid > 0));
@@ -3562,6 +3570,10 @@ export async function doctorWorld(name, options = {}) {
         return { name, ok: false, checks: [{ id: 'instance', ok: false, message }] };
     }
     checks.push({ id: 'env-file', ok: existsSync(instance.envFile), message: instance.envFile });
+    const missingServices = (instance.bootServices ?? []).filter(id => !Object.hasOwn(instance.services, id));
+    checks.push({ id: 'startup', ok: missingServices.length === 0, message: missingServices.length
+            ? `startup incomplete: no ready service record for ${missingServices.join(', ')}; retained state requires normal teardown before resume`
+            : 'declared boot services have instance records' });
     if (instance.lifecycle) {
         checks.push({ id: 'lifecycle', ok: hasWorldLifecycle(root, name) && existsSync(instance.lifecycle.log),
             message: `lifecycle ownership recorded; no capacity reserved; log=${instance.lifecycle.log}` });

package/dist/src/schema.d.ts

@@ -532,6 +532,11 @@ export type WorldInstance = {
     bootServices?: string[];
     bootOwner?: string | null;
     envFile: string;
+    /** Exact output claimed before this boot replaced its predecessor; retained only until publication completes. */
+    previousEnvOutput?: {
+        path: string;
+        sha256: string;
+    };
     pidsFile: string;
     actors?: Record<string, unknown>;
     fixtures?: Record<string, unknown>;

package/dist/src/served-world.js

@@ -1271,6 +1271,7 @@ export class WorldDoors {
                 if (template)
                     headers.set(TWIN_SITES_HEADER, template);
                 headers.set(TWIN_SITE_HEADER, pageHost);
+                headers.set(TWIN_PREFIX_HEADER, '/');
                 headers.set('x-forwarded-host', url.host);
                 headers.set('x-forwarded-proto', url.protocol.slice(0, -1));
             }
@@ -1460,6 +1461,10 @@ export class WorldDoors {
         // a person's browser opening a page at the twin's place (a navigation, or the frame the console shows it in)
         const page = request.method === 'GET' && ['document', 'iframe'].includes(request.headers.get('sec-fetch-dest') ?? '');
         const link = this.link(vendor);
+        const screenMount = tail[0] === '_screen';
+        // A declared screen mount is answered only by the twin, never forwarded to a real-system link.
+        if (screenMount && link)
+            return Response.json({ error: `${vendor} is linked to the vendor itself: no twin screen is mounted` }, { status: 404 });
         // a link spends the World's sealed vendor credential: never from the content plane, where any twin's markup runs
         if (link && this.onPages(url))
             return Response.json({ error: `${vendor} is linked to the vendor itself: it is used through the World's own origin` }, { status: 404 });
@@ -1471,6 +1476,22 @@ export class WorldDoors {
         const twin = this.host.twinFetch(vendor);
         if (!twin)
             return Response.json({ error: `no twin "${vendor}" in ${this.served}` }, { status: 404 });
+        // The Board's screen mount keeps the hostname the workspace declared. Without it, a multi-lane vendor's
+        // /redis console page is sent to its Redis data API. The mount is the World's word, checked against discovery;
+        // it survives redirects and forms through the public prefix instead of trusting a browser's routing header.
+        let screenHost;
+        if (screenMount) {
+            try {
+                screenHost = decodeURIComponent(tail[1] ?? '').toLowerCase();
+            }
+            catch {
+                return Response.json({ error: 'invalid screen hostname' }, { status: 400 });
+            }
+            if (!screenHost || !(await this.screensOf(vendor)).some(screen => screen.host?.toLowerCase() === screenHost)) {
+                return Response.json({ error: `no built workspace of ${vendor} declares that screen hostname` }, { status: 404 });
+            }
+        }
+        const vendorPath = (screenMount ? tail.slice(2) : tail).join('/');
         // THE READ SCOPE: the twin is told the request is read-only and refuses the caller's writes itself
         // (a Slack read over POST passes, a post is refused); a twin that cannot enforce that gets reads only
         const enforced = scope === 'read' && (await this.enforcesRead(vendor, twin, url.origin));
@@ -1505,7 +1526,9 @@ export class WorldDoors {
         else
             headers.delete('cookie');
         // the twin is mounted under this World's path: live URLs it mints must carry it (twinPublicBase)
-        headers.set(TWIN_PREFIX_HEADER, `/${this.served}/${vendor}`);
+        headers.set(TWIN_PREFIX_HEADER, `/${this.served}/${vendor}${screenHost ? `/_screen/${encodeURIComponent(screenHost)}` : ''}`);
+        if (screenHost)
+            headers.set('x-volter-twin-original-host', screenHost);
         headers.set('x-forwarded-host', url.host);
         headers.set('x-forwarded-proto', url.protocol.replace(':', ''));
         // where this World shows the hostnames its twins answer, for a page that links one (twinSiteUrl): under its own
@@ -1516,7 +1539,7 @@ export class WorldDoors {
         else
             headers.delete(TWIN_SITES_HEADER);
         const body = request.method === 'GET' || request.method === 'HEAD' ? undefined : await request.arrayBuffer();
-        const answer = await twin(new Request(`${url.origin}/${tail.join('/')}${url.search}`, { method: request.method, headers, ...(body === undefined ? {} : { body }), redirect: 'manual' }));
+        const answer = await twin(new Request(`${url.origin}/${vendorPath}${url.search}`, { method: request.method, headers, ...(body === undefined ? {} : { body }), redirect: 'manual' }));
         // an upgrade the twin answered (a tunnel's control or visitor socket) goes back as it is
         if (answer.status === 101)
             return answer;
@@ -1802,6 +1825,8 @@ export class WorldDoors {
                     return new Response(null, { status: 204, headers });
                 }
                 if (request.method === 'PUT') {
+                    if (request.headers.get('if-none-match') === '*' && worldBrowser(data, name))
+                        return Response.json({ error: `browser ${name} already exists; choose it or use another name` }, { status: 412 });
                     if (!/^application\/json\b/i.test(request.headers.get('content-type') ?? ''))
                         return Response.json({ error: 'browser state is application/json' }, { status: 415 });
                     if (!worldBrowser(data, name) && worldBrowsers(data).length >= BROWSER_COUNT_LIMIT)
@@ -2383,7 +2408,10 @@ export class WorldDoors {
                 const origin = readBranchMeta(state, this.controlRoot(name))?.origin;
                 const identity = { mounted: mounted?.resolvedPackage ? { package: mounted.resolvedPackage, version: mounted.resolvedVersion ?? null } : null, pinned: mounted?.pinnedSource ?? null };
                 const dataOrigin = origin ? { kind: 'shared-history', url: origin.at } : refresh ? { kind: 'vendor-refresh', url: root?.url ?? null } : { kind: 'unrecorded', url: null };
-                return Response.json({ twin: name, state, identity, dataOrigin, execution: { rootConnected: Boolean(root), deploy: root?.deploy ?? null }, protocol: mounted?.protocol ?? null, screens: await this.screensOf(name), resources: this.workspaces.get(name)?.resources ?? {}, root: root ?? null, credential: sealedCredentialInfo(this.worldRoot, name), refresh, position: wholeLog(state, this.controlRoot(name)).length, lastReceipt: last?.receipt ?? null });
+                const claimed = await this.claimedHosts(url.origin);
+                const sites = (await this.browserSites(url.origin, claimed)).find(row => row.vendor === name)?.hosts ?? [];
+                const readOnlySites = claimed.find(row => row.vendor === name)?.hosts ?? [];
+                return Response.json({ twin: name, state, identity, dataOrigin, execution: { rootConnected: Boolean(root), deploy: root?.deploy ?? null }, protocol: mounted?.protocol ?? null, screens: await this.screensOf(name), sites, readOnlySites, resources: this.workspaces.get(name)?.resources ?? {}, root: root ?? null, credential: sealedCredentialInfo(this.worldRoot, name), refresh, position: wholeLog(state, this.controlRoot(name)).length, lastReceipt: last?.receipt ?? null });
             }
             if (verb === 'refresh' && request.method === 'POST') {
                 const root = rootForControlRoot(this.controlRoot(name), name);
@@ -2719,9 +2747,14 @@ export class WorldDoors {
             // a pack that lays out no board yet keeps its vendor's home on it (its root workspace, else its first unparameterized
             // one), whose changes are all of the vendor's
             const fallback = !listed.length;
+            const screens = await this.screensOf(vendor);
+            const screenPath = (path, hostname) => {
+                const host = hostname?.toLowerCase();
+                return host && !/[{<]/.test(host) && screens.some(screen => screen.host?.toLowerCase() === host)
+                    ? `/_screen/${encodeURIComponent(host)}${path}` : path;
+            };
             let homeHost;
             if (fallback) {
-                const screens = await this.screensOf(vendor);
                 const home = screens.find((w) => w.path.replace(/\/+$/, '') === '') ?? screens.find((w) => !/[{<]/.test(w.path));
                 homeHost = home?.host;
                 if (home)
@@ -2785,7 +2818,7 @@ export class WorldDoors {
                             at = { site: opened };
                     }
                     else if (f.drawn)
-                        at = { screen: `${u.pathname}${u.search}` };
+                        at = { screen: screenPath(`${u.pathname}${u.search}`, u.hostname) };
                     if (!at)
                         unseen = claimed.get(vendor)?.has(u.hostname.toLowerCase()) ? 'sites-not-routed' : 'not-drawn';
                 }
@@ -2796,7 +2829,7 @@ export class WorldDoors {
                         unseen = 'not-drawn';
                 }
                 if (fallback)
-                    at = { screen: f.url.startsWith('/') ? f.url : `/${f.url}` };
+                    at = { screen: screenPath(f.url.startsWith('/') ? f.url : `/${f.url}`, homeHost) };
                 add(at, undefined, unseen);
             }
         }

package/dist/src/up-cli.d.ts

@@ -1,3 +1,3 @@
 import type { upWorld } from './runtime.js';
 export declare function upCommand(subject: string | undefined, rest: string[], root: string): Promise<void>;
-export declare function printReady(instance: Awaited<ReturnType<typeof upWorld>>): void;
+export declare function printReady(instance: Awaited<ReturnType<typeof upWorld>>, fresh?: boolean): void;

package/dist/src/up-cli.js

@@ -44,7 +44,7 @@ export async function upCommand(subject, rest, root) {
     if (rest.includes('--json'))
         process.stdout.write(JSON.stringify(instance, null, 2) + '\n');
     else
-        printReady(instance);
+        printReady(instance, !keepState);
 }
 async function upInProcess(configId, options) {
     const { upWorld } = await import("./runtime.js");
@@ -60,7 +60,7 @@ async function upInProcess(configId, options) {
         process.off('SIGTERM', cancel);
     }
 }
-export function printReady(instance) {
+export function printReady(instance, fresh = false) {
     process.stdout.write(`World ${instance.name} is ready (${instance.config})
 Instance: ${instance.instance}
 Created: ${instance.createdAt}
@@ -68,8 +68,8 @@ Created: ${instance.createdAt}
 Services:
 ${Object.values(instance.services).map((service) => `  ${service.id}: ${service.url ?? '(no listener — a World output)'}`).join('\n')}
 
-This instance started CLEAN (a world's state lives only while it runs; the world dir is the
-reproducible story) — set the clock and run your seed now, after every up.
+${fresh ? 'This is a fresh instance. Set the clock and run your seed before the application.'
+        : 'This World retains its branch state. Continue with the application; do not seed its records again.'}
 
 The two moves: if the twin stores it, create it through the vendor's own API (seed as the
 person, move the clock first for history). Everything else — judgment, lookups, faults — is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-runtime",
-  "version": "3.0.145",
+  "version": "3.0.147",
   "description": "World configs for twins: boot named local runtimes, allocate ports, generate world.env/instance.json, and run apps against fake-key twin worlds.",
   "keywords": [
     "twin",
@@ -70,14 +70,14 @@
     "node": ">=22.3"
   },
   "peerDependencies": {
-    "@volter/world-core": "3.0.145",
-    "@volter/world-console": "3.0.140"
+    "@volter/world-core": "3.0.147",
+    "@volter/world-console": "3.0.142"
   },
   "dependencies": {
     "@electric-sql/pglite": "0.5.8",
     "@electric-sql/pglite-pgvector": "0.0.9",
     "@volter/world-access": "3.0.1",
-    "@volter/world-core": "3.0.145",
+    "@volter/world-core": "3.0.147",
     "mongodb": "~6.20.0",
     "pg-gateway": "0.3.0-beta.4",
     "smol-toml": "^1.8.0",

package/src/covers.ts

@@ -1125,11 +1125,12 @@ export function formatCoverageReport(report: CoverageReport): string {
   if (report.acknowledged.length > 0) {
     lines.push(`ACKNOWLEDGED: ${report.acknowledged.length} signal(s) accepted with recorded reasons (no twin): ${report.acknowledged.map((a) => a.vendor).join(', ')}`);
   }
-  if (report.excluded.length > 0) lines.push(`EXCLUDED BY SELECTION: ${report.excluded.join(', ')} (not covered; no access granted).`);
+  if (report.excluded.length > 0) lines.push(`EXCLUDED BY SELECTION: ${report.excluded.join(', ')} (outside automatic selection; declared service bindings are reported separately).`);
+  const detectionScope = report.excluded.length > 0 ? 'selected detected vendor' : 'detected vendor';
   lines.push(report.ok
     ? report.acknowledged.length > 0
-      ? `COVERED (with ${report.acknowledged.length} acknowledgment(s)): every other detected vendor has a twin in world ${report.world}.`
-      : `COVERED: every detected vendor has a twin in world ${report.world}.`
+      ? `COVERED (with ${report.acknowledged.length} acknowledgment(s)): every other ${detectionScope} has a twin in world ${report.world}.`
+      : `COVERED: every ${detectionScope} has a twin in world ${report.world}.`
     : `PROOF FAILED for world ${report.world}.`);
   lines.push('Static connection check only; run an app scenario to verify behavior and shared state.');
   return `${lines.join('\n')}\n`;

package/src/env-output.ts

@@ -2,7 +2,7 @@ import { constants, closeSync, existsSync, fstatSync, ftruncateSync, lstatSync,
 import { dirname, join } from 'node:path';
 import { createHash } from 'node:crypto';
 
-type PriorOutput = { path: string; contents: string };
+type PriorOutput = { path: string; contents: string; sha256?: string };
 export type EnvOutputClaim = { path: string; contents?: Buffer; force: boolean; backupDir: string };
 
 function inspect(path: string): Buffer | undefined {
@@ -19,7 +19,10 @@ function inspect(path: string): Buffer | undefined {
 /** Refuse a custody/input file before any World service or lifecycle mutation starts. */
 export function claimEnvOutput(path: string, backupDir: string, priors: PriorOutput[] = [], force = false): EnvOutputClaim {
   const contents = inspect(path);
-  if (contents !== undefined && !force && !priors.some((prior) => prior.path === path && Buffer.from(prior.contents).equals(contents))) {
+  if (contents !== undefined && !force && !priors.some((prior) => prior.path === path && (
+    Buffer.from(prior.contents).equals(contents)
+    || /^[a-f0-9]{64}$/.test(prior.sha256 ?? '') && createHash('sha256').update(contents).digest('hex') === prior.sha256
+  ))) {
     throw new Error(`World refuses existing --env-out file it does not own: ${path}. Choose a new output path; never use a custody file. --force explicitly replaces a file with a private backup.`);
   }
   if (force && contents !== undefined) {

package/src/init.ts

@@ -122,6 +122,8 @@ export type EnvDisposition =
   | 'faked'
   /** a credential the vendor's twin issues at boot → `$issue:<vendor>` (the twin refuses a key it did not make) */
   | 'issued'
+  /** a World-owned endpoint or reserved environment name → supplied at boot, never copied from the app */
+  | 'injected'
   /** non-credential app config → the example value copied verbatim */
   | 'kept'
   /** infra connection string → points at a World-managed infrastructure service */
@@ -926,7 +928,7 @@ export function planWorldInit(name: string, repoPath: string, options: InitOptio
     // World-owned names: the world INJECTS these at boot from the services above. Carrying a repo's
     // stale copy would shadow the live one.
     if (/_TWIN_URL$/.test(name) || /^VOLTER_/.test(name) || worldInjected.has(name)) {
-      envRows.push({ name, disposition: 'unknown', source, reason: 'world-owned (injected at boot) — dropped from the emitted env' });
+      envRows.push({ name, disposition: 'injected', source, reason: 'world-owned (injected at boot) — dropped from the emitted env' });
       continue;
     }
     // The application's own origin (its base URL, its auth library's URL): only the booter knows where the app is
@@ -1514,7 +1516,7 @@ export function formatInitReport(result: InitResult): string {
   lines.push('');
   const counts = (disposition: EnvDisposition): InitEnvRow[] => plan.envRows.filter((row) => row.disposition === disposition);
   lines.push(`Env (${plan.envRows.length} name(s) from ${plan.envSources.join(', ') || 'no example env file'}):`);
-  for (const disposition of ['faked', 'kept', 'app-origin', 'stand-in', 'compose', 'placeholder', 'unknown'] as EnvDisposition[]) {
+  for (const disposition of ['faked', 'issued', 'injected', 'kept', 'app-origin', 'stand-in', 'compose', 'placeholder', 'unknown'] as EnvDisposition[]) {
     const rows = counts(disposition);
     if (rows.length === 0) continue;
     lines.push(`  ${disposition.padEnd(11)} ${String(rows.length).padStart(3)}  ${rows.map((row) => row.name).join(', ')}`);

package/src/runtime.ts

@@ -698,8 +698,8 @@ function readWorldBootRecordLocked(name: string, root: string): WorldInstance {
     }
     if (!Array.isArray(record.bootServices) || record.bootServices.some(id => typeof id !== 'string')
       || new Set(record.bootServices).size !== record.bootServices.length
-      || record.bootServices.length !== Object.keys(record.services).length
-      || record.bootServices.some(id => !Object.hasOwn(record.services, id))) throw new Error();
+      || Object.keys(record.services).some(id => !record.bootServices!.includes(id))
+      || !stopped && record.bootServices.length !== Object.keys(record.services).length) throw new Error();
     for (const [id, service] of Object.entries(record.services)) {
       if (!service || service.id !== id || !Array.isArray(service.command) || typeof service.type !== 'string') throw new Error();
       if (!Object.hasOwn(service, 'branchState')) {
@@ -716,7 +716,7 @@ function readWorldBootRecordLocked(name: string, root: string): WorldInstance {
         instanceHash: createHash('sha256').update(readFileSync(path, 'utf8')).digest('hex') }) + '\n');
     }
     return record;
-  } catch { throw new Error(`World boot record is incomplete or invalid: ${path}`); }
+  } catch { throw new Error(`World boot record is incomplete or invalid: ${path}\nFrom the app directory, inspect: volter-world doctor ${name} --root .\nComplete teardown with the owning runtime: volter-world down ${name} --root .\nRetain the startup diagnostics and any history. Only a disposable instance with no state to keep may be removed with down --purge; resume never discards it automatically.`); }
 }
 
 export function admittedEnv(strip: string[] | undefined, env: NodeJS.ProcessEnv = process.env): Record<string, string> {
@@ -1961,7 +1961,9 @@ export async function upWorld(configId: string, options: UpWorldOptions = {}, ab
     if (!existsSync(file)) return [];
     try {
       const prior = JSON.parse(readFileSync(file, 'utf8')) as WorldInstance;
-      return prior?.name === world && resolve(prior.root) === root ? [{ path: resolve(prior.envFile), contents: envFileContents(prior.env) }] : [];
+      return prior?.name === world && resolve(prior.root) === root ? [{ path: resolve(prior.envFile), contents: envFileContents(prior.env),
+        ...(prior.previousEnvOutput?.path === resolve(prior.envFile) ? { sha256: prior.previousEnvOutput.sha256 } : {}),
+      }] : [];
     } catch { return []; }
   });
   const envOutputClaim = claimEnvOutput(envFile, join(root, stateDirName(), 'env-output-backups'), priorOutputs, options.forceEnvOutput);
@@ -2129,6 +2131,7 @@ export async function upWorld(configId: string, options: UpWorldOptions = {}, ab
     const worldInstance: WorldInstance = {
       name, instance: instanceToken, config: loaded.config.id, configPath: loaded.path, root, createdAt, mode,
       dirs: { instance, logs, data }, services, env, envFile, pidsFile,
+      ...(envOutputClaim.contents === undefined ? {} : { previousEnvOutput: { path: envFile, sha256: createHash('sha256').update(envOutputClaim.contents).digest('hex') } }),
       networkCeiling: env[WORLD_NETWORK_POLICY_ENV] === undefined ? 'unrestricted' : networkPermission(parseWorldNetworkPolicy(JSON.parse(env[WORLD_NETWORK_POLICY_ENV]!))),
       bootServices: loaded.config.services.map(service => service.id), bootOwner: options.owner ?? null,
       ...(loaded.config.selection ? { selection: loaded.config.selection } : {}),
@@ -2274,7 +2277,12 @@ export async function upWorld(configId: string, options: UpWorldOptions = {}, ab
       mkdirSync(dirname(envFile), { recursive: true });
       // Config env and discovered credentials: a file this writes is owner-only; a file the caller already made keeps
       // the mode the caller chose (a shared env file may be read under another uid).
+      // Persist final environment identity while the claimed old output is still recoverable; caller loss between
+      // this record and publication must not make the old file appear to be custody.
+      saveWorldInstance(worldInstance);
       publishEnvOutput(envOutputClaim, envFileContents(env));
+      delete worldInstance.previousEnvOutput;
+      saveWorldInstance(worldInstance);
       boot.progress(`environment written: ${envFile}`);
       materializeBrowserFiles(data, root, name, loaded.config.id);
       writePidsFromInstance(worldInstance, Object.values(worldInstance.services).map((service) => service.pid).filter((pid) => pid > 0));
@@ -3360,6 +3368,10 @@ export async function doctorWorld(name: string, options: { root?: string; verify
   }
 
   checks.push({ id: 'env-file', ok: existsSync(instance.envFile), message: instance.envFile });
+  const missingServices = (instance.bootServices ?? []).filter(id => !Object.hasOwn(instance.services, id));
+  checks.push({ id: 'startup', ok: missingServices.length === 0, message: missingServices.length
+    ? `startup incomplete: no ready service record for ${missingServices.join(', ')}; retained state requires normal teardown before resume`
+    : 'declared boot services have instance records' });
 
   if (instance.lifecycle) {
     checks.push({ id: 'lifecycle', ok: hasWorldLifecycle(root, name) && existsSync(instance.lifecycle.log),

package/src/schema.ts

@@ -463,6 +463,8 @@ export type WorldInstance = {
   bootServices?: string[];
   bootOwner?: string | null;
   envFile: string;
+  /** Exact output claimed before this boot replaced its predecessor; retained only until publication completes. */
+  previousEnvOutput?: { path: string; sha256: string };
   pidsFile: string;
   actors?: Record<string, unknown>;
   fixtures?: Record<string, unknown>;

package/src/served-world.ts

@@ -1133,6 +1133,7 @@ export class WorldDoors {
         const template = this.host.sitesTemplate?.();
         if (template) headers.set(TWIN_SITES_HEADER, template);
         headers.set(TWIN_SITE_HEADER, pageHost);
+        headers.set(TWIN_PREFIX_HEADER, '/');
         headers.set('x-forwarded-host', url.host);
         headers.set('x-forwarded-proto', url.protocol.slice(0, -1));
       }
@@ -1294,6 +1295,9 @@ export class WorldDoors {
     // a person's browser opening a page at the twin's place (a navigation, or the frame the console shows it in)
     const page = request.method === 'GET' && ['document', 'iframe'].includes(request.headers.get('sec-fetch-dest') ?? '');
     const link = this.link(vendor!);
+    const screenMount = tail[0] === '_screen';
+    // A declared screen mount is answered only by the twin, never forwarded to a real-system link.
+    if (screenMount && link) return Response.json({ error: `${vendor} is linked to the vendor itself: no twin screen is mounted` }, { status: 404 });
     // a link spends the World's sealed vendor credential: never from the content plane, where any twin's markup runs
     if (link && this.onPages(url)) return Response.json({ error: `${vendor} is linked to the vendor itself: it is used through the World's own origin` }, { status: 404 });
     if (link) {
@@ -1302,6 +1306,18 @@ export class WorldDoors {
     }
     const twin = this.host.twinFetch(vendor!);
     if (!twin) return Response.json({ error: `no twin "${vendor}" in ${this.served}` }, { status: 404 });
+    // The Board's screen mount keeps the hostname the workspace declared. Without it, a multi-lane vendor's
+    // /redis console page is sent to its Redis data API. The mount is the World's word, checked against discovery;
+    // it survives redirects and forms through the public prefix instead of trusting a browser's routing header.
+    let screenHost: string | undefined;
+    if (screenMount) {
+      try { screenHost = decodeURIComponent(tail[1] ?? '').toLowerCase(); }
+      catch { return Response.json({ error: 'invalid screen hostname' }, { status: 400 }); }
+      if (!screenHost || !(await this.screensOf(vendor!)).some(screen => screen.host?.toLowerCase() === screenHost)) {
+        return Response.json({ error: `no built workspace of ${vendor} declares that screen hostname` }, { status: 404 });
+      }
+    }
+    const vendorPath = (screenMount ? tail.slice(2) : tail).join('/');
     // THE READ SCOPE: the twin is told the request is read-only and refuses the caller's writes itself
     // (a Slack read over POST passes, a post is refused); a twin that cannot enforce that gets reads only
     const enforced = scope === 'read' && (await this.enforcesRead(vendor!, twin, url.origin));
@@ -1323,14 +1339,15 @@ export class WorldDoors {
     const cookies = (headers.get('cookie') ?? '').split(/;\s*/).filter((c) => c && !/^(?:__Host-)?volter_(?:world|pages)=/.test(c));
     if (cookies.length) headers.set('cookie', cookies.join('; ')); else headers.delete('cookie');
     // the twin is mounted under this World's path: live URLs it mints must carry it (twinPublicBase)
-    headers.set(TWIN_PREFIX_HEADER, `/${this.served}/${vendor}`);
+    headers.set(TWIN_PREFIX_HEADER, `/${this.served}/${vendor}${screenHost ? `/_screen/${encodeURIComponent(screenHost)}` : ''}`);
+    if (screenHost) headers.set('x-volter-twin-original-host', screenHost);
     headers.set('x-forwarded-host', url.host); headers.set('x-forwarded-proto', url.protocol.replace(':', ''));
     // where this World shows the hostnames its twins answer, for a page that links one (twinSiteUrl): under its own
     // origin on this machine (siteOfHost); a World without one shows none
     const sitesAt = this.host.sitesTemplate?.() ?? null;
     if (sitesAt) headers.set(TWIN_SITES_HEADER, sitesAt); else headers.delete(TWIN_SITES_HEADER);
     const body = request.method === 'GET' || request.method === 'HEAD' ? undefined : await request.arrayBuffer();
-    const answer = await twin(new Request(`${url.origin}/${tail.join('/')}${url.search}`, { method: request.method, headers, ...(body === undefined ? {} : { body }), redirect: 'manual' }));
+    const answer = await twin(new Request(`${url.origin}/${vendorPath}${url.search}`, { method: request.method, headers, ...(body === undefined ? {} : { body }), redirect: 'manual' }));
     // an upgrade the twin answered (a tunnel's control or visitor socket) goes back as it is
     if (answer.status === 101) return answer;
     // staleness is a fact on the wire: a twin with a root says when the vendor was last observed
@@ -1554,6 +1571,7 @@ export class WorldDoors {
           return new Response(null, { status: 204, headers });
         }
         if (request.method === 'PUT') {
+          if (request.headers.get('if-none-match') === '*' && worldBrowser(data, name)) return Response.json({ error: `browser ${name} already exists; choose it or use another name` }, { status: 412 });
           if (!/^application\/json\b/i.test(request.headers.get('content-type') ?? '')) return Response.json({ error: 'browser state is application/json' }, { status: 415 });
           if (!worldBrowser(data, name) && worldBrowsers(data).length >= BROWSER_COUNT_LIMIT) return Response.json({ error: `a World holds at most ${BROWSER_COUNT_LIMIT} browsers; delete one before adding another` }, { status: 409 });
           const oversized = (): Response => Response.json({ error: `browser state PUT body is limited to ${BROWSER_STATE_BYTES_LIMIT} bytes (1 MiB)` }, { status: 413 });
@@ -1992,7 +2010,10 @@ export class WorldDoors {
         const origin = readBranchMeta(state, this.controlRoot(name))?.origin;
         const identity = { mounted: mounted?.resolvedPackage ? { package: mounted.resolvedPackage, version: mounted.resolvedVersion ?? null } : null, pinned: mounted?.pinnedSource ?? null };
         const dataOrigin = origin ? { kind: 'shared-history', url: origin.at } : refresh ? { kind: 'vendor-refresh', url: root?.url ?? null } : { kind: 'unrecorded', url: null };
-        return Response.json({ twin: name, state, identity, dataOrigin, execution: { rootConnected: Boolean(root), deploy: root?.deploy ?? null }, protocol: mounted?.protocol ?? null, screens: await this.screensOf(name), resources: this.workspaces.get(name)?.resources ?? {}, root: root ?? null, credential: sealedCredentialInfo(this.worldRoot, name), refresh, position: wholeLog(state, this.controlRoot(name)).length, lastReceipt: last?.receipt ?? null });
+        const claimed = await this.claimedHosts(url.origin);
+        const sites = (await this.browserSites(url.origin, claimed)).find(row => row.vendor === name)?.hosts ?? [];
+        const readOnlySites = claimed.find(row => row.vendor === name)?.hosts ?? [];
+        return Response.json({ twin: name, state, identity, dataOrigin, execution: { rootConnected: Boolean(root), deploy: root?.deploy ?? null }, protocol: mounted?.protocol ?? null, screens: await this.screensOf(name), sites, readOnlySites, resources: this.workspaces.get(name)?.resources ?? {}, root: root ?? null, credential: sealedCredentialInfo(this.worldRoot, name), refresh, position: wholeLog(state, this.controlRoot(name)).length, lastReceipt: last?.receipt ?? null });
       }
       if (verb === 'refresh' && request.method === 'POST') {
         const root = rootForControlRoot(this.controlRoot(name), name);
@@ -2270,9 +2291,14 @@ export class WorldDoors {
       // a pack that lays out no board yet keeps its vendor's home on it (its root workspace, else its first unparameterized
       // one), whose changes are all of the vendor's
       const fallback = !listed.length;
+      const screens = await this.screensOf(vendor);
+      const screenPath = (path: string, hostname?: string): string => {
+        const host = hostname?.toLowerCase();
+        return host && !/[{<]/.test(host) && screens.some(screen => screen.host?.toLowerCase() === host)
+          ? `/_screen/${encodeURIComponent(host)}${path}` : path;
+      };
       let homeHost: string | undefined;
       if (fallback) {
-        const screens = await this.screensOf(vendor);
         const home = screens.find((w) => w.path.replace(/\/+$/, '') === '') ?? screens.find((w) => !/[{<]/.test(w.path));
         homeHost = home?.host;
         if (home) listed = [{ id: `home:${home.id}`, kind: 'home', title: vendor, section: { id: 'home', title: 'Home' }, url: home.path, covers: [], drawn: true }];
@@ -2320,10 +2346,10 @@ export class WorldDoors {
             const opened = siteAt(u.hostname.toLowerCase(), `${u.pathname}${u.search}`);
             if (opened) at = { site: opened };
           }
-          else if (f.drawn) at = { screen: `${u.pathname}${u.search}` };
+          else if (f.drawn) at = { screen: screenPath(`${u.pathname}${u.search}`, u.hostname) };
           if (!at) unseen = claimed.get(vendor)?.has(u.hostname.toLowerCase()) ? 'sites-not-routed' : 'not-drawn';
         } catch { if (fallback) at = { screen: f.url.startsWith('/') ? f.url : `/${f.url}` }; else unseen = 'not-drawn'; }
-        if (fallback) at = { screen: f.url.startsWith('/') ? f.url : `/${f.url}` };
+        if (fallback) at = { screen: screenPath(f.url.startsWith('/') ? f.url : `/${f.url}`, homeHost) };
         add(at, undefined, unseen);
       }
     }

package/src/up-cli.ts

@@ -40,7 +40,7 @@ export async function upCommand(subject: string | undefined, rest: string[], roo
     process.stderr.write(`volter-world up ${instance.name}: app url recorded: ${appUrl}\n`);
   }
   if (rest.includes('--json')) process.stdout.write(JSON.stringify(instance, null, 2) + '\n');
-  else printReady(instance);
+  else printReady(instance, !keepState);
 }
 
 async function upInProcess(configId: string, options: Parameters<typeof upWorld>[1]): Promise<Awaited<ReturnType<typeof upWorld>>> {
@@ -52,7 +52,7 @@ async function upInProcess(configId: string, options: Parameters<typeof upWorld>
   finally { process.off('SIGINT', cancel); process.off('SIGTERM', cancel); }
 }
 
-export function printReady(instance: Awaited<ReturnType<typeof upWorld>>): void {
+export function printReady(instance: Awaited<ReturnType<typeof upWorld>>, fresh = false): void {
   process.stdout.write(`World ${instance.name} is ready (${instance.config})
 Instance: ${instance.instance}
 Created: ${instance.createdAt}
@@ -60,8 +60,8 @@ Created: ${instance.createdAt}
 Services:
 ${Object.values(instance.services).map((service) => `  ${service.id}: ${service.url ?? '(no listener — a World output)'}`).join('\n')}
 
-This instance started CLEAN (a world's state lives only while it runs; the world dir is the
-reproducible story) — set the clock and run your seed now, after every up.
+${fresh ? 'This is a fresh instance. Set the clock and run your seed before the application.'
+  : 'This World retains its branch state. Continue with the application; do not seed its records again.'}
 
 The two moves: if the twin stores it, create it through the vendor's own API (seed as the
 person, move the clock first for history). Everything else — judgment, lookups, faults — is