@volter/world 3.0.164 → 3.0.166

package/dist/examples/customer-onboarding/README.md

@@ -13,7 +13,7 @@ You need Node 22.6+, npm and registry access during installation. The browser pa
 Copy this starter into a new folder:
 
 ```console
-$ npx @volter/world@3.0.164 example customer-onboarding --dir onboarding
+$ npx @volter/world@3.0.166 example customer-onboarding --dir onboarding
 $ cd onboarding
 $ npm install
 ```
@@ -41,6 +41,8 @@ $ ./node_modules/.bin/volter world log
 
 Read the customer returned by Stripe, the signup row returned by SQL and the email returned by Resend. `completion: complete` means delivery was observed, not merely that a send request was accepted. Opaque IDs can differ between fresh Worlds; customer identity, stored fields and delivery status are the useful outcomes.
 
+The SQL `completion` column retains the last send result. `run.mjs read` and the browser combine that saved row with Resend's current `last_event` to derive `complete` or `partial-email-bounced`. Observing delivery leaves the SQL row unchanged.
+
 ## Observe two different failures
 
 A refusing recipient's mail server creates a bounce after the send was accepted:
@@ -83,16 +85,29 @@ Then start the app through the World:
 $ ./node_modules/.bin/volter world run -- node server.mjs
 ```
 
-Open the printed app URL in your browser. Submit a signup, advance the World clock in another terminal and reload. The page shows the completion state and full stored outcome. Its server registers its app URL with the World after listening; consumers can discover it with `world app-url`.
+The server registers its app URL with the World after listening. In another terminal, from the same application folder, read that endpoint with the installed operator command:
+
+```console
+$ ./node_modules/.bin/volter-world app-url onboarding --root .
+```
+
+`onboarding` is the World name selected by the init command above; use your current branch's name if you have branched. `--root .` selects this application's World. Open the returned URL or the server's printed app URL in your browser. Submit a signup, advance the World clock in another terminal and reload. The page shows the completion state and full stored outcome. [The CLI reference](https://world.volter.ai/docs/reference/cli.html#the-world-itself) describes endpoint discovery and registration.
+
+To have the World start and stop the app with its services, declare `server.mjs` as a process service using [run a full stack](https://world.volter.ai/docs/guides/run-a-full-stack.html#the-app-as-a-service). This server honors the World-assigned `PORT`; use `/` as its HTTP readiness path. The manual command above chooses an available port when `PORT` is absent.
 
-To open the World dashboard, stop the app with Ctrl-C first, then switch the owned compute to the viewer:
+To open the World dashboard, switch the owned compute to the viewer. If you started the app
+manually with `world run`, stop that app with Ctrl-C first. If you declared it as a process
+service, the `down` command below stops it with the World's other services:
 
 ```console
 $ ./node_modules/.bin/volter world down
 $ ./node_modules/.bin/volter world view --no-open
 ```
 
-The viewer prints the dashboard URL and keeps running. Start `world run -- node server.mjs` in a second terminal if you want the application alongside it. Open **Stripe** under **Records**, then select the customer to inspect its name, email and stored ID. Open **Resend** to inspect the accepted email and delivery event. **Board** opens the vendor pages declared by the installed twin; its root workspace may cover settings rather than customers. Provisioning remains in full history even when hidden from the business-activity view. Read the application's SQL completion record with `run.mjs read` or its browser page.
+The viewer prints the dashboard URL and keeps running. In manual app mode, start
+`world run -- node server.mjs` in a second terminal if you want the application alongside it.
+With a declared process service, the viewer starts the app as part of the World; no second
+app command is needed. Open **Stripe** under **Records**, then select the customer to inspect its name, email and stored ID. Open **Resend** to inspect the accepted email and delivery event. **Board** opens the vendor pages declared by the installed twin; its root workspace may cover settings rather than customers. Provisioning remains in full history even when hidden from the business-activity view. Read the application's combined signup, customer and delivery result with `run.mjs read` or its browser page.
 
 Stop app consumers before stopping the viewer. `down` retains vendor and declared application state. [Resume](https://world.volter.ai/docs/guides/resume-a-world.html) explains continuing it; [demo a workflow](https://world.volter.ai/docs/guides/demo-a-workflow.html) uses this same application for a repeatable baseline, refusal and retry. Reset only your disposable example World; it discards that branch's work.
 

package/dist/examples/customer-onboarding/package.json

@@ -11,11 +11,12 @@
     "pg": "8.16.3"
   },
   "devDependencies": {
-    "@volter/world": "3.0.164",
-    "@volter/world-core": "3.0.154",
-    "@volter/world-runtime": "3.0.162",
-    "@volter/world-console": "3.0.150",
+    "@volter/world": "3.0.166",
+    "@volter/world-core": "3.0.155",
+    "@volter/world-runtime": "3.0.163",
+    "@volter/world-console": "3.0.151",
     "@volter/twin-stripe": "3.0.2",
-    "@volter/twin-resend": "1.0.1"
+    "@volter/twin-resend": "1.0.1",
+    "@volter/world-ui": "1.0.155"
   }
 }

package/dist/examples/customer-onboarding/server.mjs

@@ -25,7 +25,7 @@ const server = createServer(async (request, response) => {
     response.end(`<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width"><title>Customer onboarding</title><link rel="stylesheet" href="/brand/tokens.css"><link rel="stylesheet" href="/style.css"><main><header><img src="/brand/world.svg" width="32" height="32" alt="Volter World"><h1>Customer onboarding</h1></header><p>Create a customer, save an application row and request a welcome email.</p><form method="post" action="/signup"><label>Name <input name="name" value="Ada" required></label><label>Email <input name="email" type="email" value="owner@world.test" required></label><button>Create account</button></form><h2>Accounts</h2><p>Reload after advancing the World clock to observe delivery. A refused email leaves the customer and application row intact.</p>${rows.map(r => `<article><h3>${escape(r.name)}</h3><p>${escape(r.email)} · <strong>${escape(r.completion)}</strong></p><p>Stripe: <code>${escape(r.customer_id)}</code> · Email: <code>${escape(r.email_id ?? 'not accepted')}</code></p><details><summary>Stored outcome</summary><pre>${escape(JSON.stringify(r, null, 2))}</pre></details></article>`).join('') || '<p>No customers yet.</p>'}</main></html>`);
   } catch (error) { response.writeHead(500, { 'Content-Type': 'text/plain' }); response.end(error.message); }
 });
-await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
+await new Promise(resolve => server.listen(Number(process.env.PORT ?? 0), '127.0.0.1', resolve));
 const url = `http://127.0.0.1:${server.address().port}`;
 setAppUrl(process.env.VOLTER_WORLD, url, { root: process.cwd() });
 console.log(`Customer onboarding ${url}`);

package/dist/examples/integration-branches/README.md

@@ -13,7 +13,7 @@ Give two workers the same Stripe baseline, let them change different existing cu
 Use an empty parent folder. Create the baseline starter there:
 
 ```console
-$ npx @volter/world@3.0.164 example integration-branches --dir baseline
+$ npx @volter/world@3.0.166 example integration-branches --dir baseline
 $ cd baseline
 $ npm install
 $ ./node_modules/.bin/volter world init --name baseline --twins stripe
@@ -38,9 +38,9 @@ The stopped baseline retains its history and can supply local path remotes. Defa
 Create three more copies in the same parent folder:
 
 ```console
-$ npx @volter/world@3.0.164 example integration-branches --dir integration
-$ npx @volter/world@3.0.164 example integration-branches --dir worker-a
-$ npx @volter/world@3.0.164 example integration-branches --dir worker-b
+$ npx @volter/world@3.0.166 example integration-branches --dir integration
+$ npx @volter/world@3.0.166 example integration-branches --dir worker-a
+$ npx @volter/world@3.0.166 example integration-branches --dir worker-b
 ```
 
 In `integration`, then `worker-a`, then `worker-b`, install dependencies and initialize with the folder's name. Before a first boot or app write, link and pull the baseline:

package/dist/examples/integration-branches/package.json

@@ -9,10 +9,11 @@
     "stripe": "17.7.0"
   },
   "devDependencies": {
-    "@volter/world": "3.0.164",
-    "@volter/world-core": "3.0.154",
-    "@volter/world-runtime": "3.0.162",
-    "@volter/world-console": "3.0.150",
-    "@volter/twin-stripe": "3.0.2"
+    "@volter/world": "3.0.166",
+    "@volter/world-core": "3.0.155",
+    "@volter/world-runtime": "3.0.163",
+    "@volter/world-console": "3.0.151",
+    "@volter/twin-stripe": "3.0.2",
+    "@volter/world-ui": "1.0.155"
   }
 }

package/dist/examples/workplace-agent/README.md

@@ -19,7 +19,7 @@ A catalog page may select a newer default. Keep this example's manifest and inst
 together; its recorded workflow does not establish behavior for a different release.
 
 ```console
-$ npx @volter/world@3.0.164 example workplace-agent --dir workplace
+$ npx @volter/world@3.0.166 example workplace-agent --dir workplace
 $ cd workplace
 $ npm install
 $ ./node_modules/.bin/volter world init --name workplace --twins github,linear,slack

package/dist/examples/workplace-agent/package.json

@@ -11,12 +11,13 @@
     "@slack/web-api": "7.19.0"
   },
   "devDependencies": {
-    "@volter/world": "3.0.164",
-    "@volter/world-core": "3.0.154",
-    "@volter/world-runtime": "3.0.162",
-    "@volter/world-console": "3.0.150",
+    "@volter/world": "3.0.166",
+    "@volter/world-core": "3.0.155",
+    "@volter/world-runtime": "3.0.163",
+    "@volter/world-console": "3.0.151",
     "@volter/twin-github": "3.0.9",
     "@volter/twin-linear": "3.0.5",
-    "@volter/twin-slack": "3.0.8"
+    "@volter/twin-slack": "3.0.8",
+    "@volter/world-ui": "1.0.155"
   }
 }

package/dist/src/agents.d.ts

@@ -2,7 +2,7 @@ export type Agent = 'claude' | 'cursor' | 'vscode' | 'codex';
 export declare const AGENTS: readonly Agent[];
 /** The skill's folder: the one shipped in the package (skills/, copied in at pack time), else this checkout's. */
 export declare function skillSource(): string;
-/** How an agent starts the server: `volter mcp` when the command is on PATH, else this installation by its path. */
+/** Start this installation's server under this runtime; PATH may contain another version of `volter`. */
 export declare function mcpCommand(): {
     command: string;
     args: string[];

package/dist/src/agents.js

@@ -32,10 +32,8 @@ export function skillSource() {
     }
     throw new Error('the volter-world skill is not in this installation (skills/volter-world)');
 }
-/** How an agent starts the server: `volter mcp` when the command is on PATH, else this installation by its path. */
+/** Start this installation's server under this runtime; PATH may contain another version of `volter`. */
 export function mcpCommand() {
-    if (which('volter'))
-        return { command: 'volter', args: ['mcp'] };
     const cli = fileURLToPath(new URL(`./cli${import.meta.url.endsWith('.ts') ? '.ts' : '.js'}`, import.meta.url));
     return { command: process.execPath, args: [cli, 'mcp'] };
 }

package/dist/src/cli.js

@@ -4,7 +4,7 @@
 // cwd; `volter twin <vendor> …` runs one twin on its own; `volter remote …` is the hosted remote.
 // One client of `World`; it adds nothing the SDK does not have.
 import { detectRepoVendors, errorMessage, formatInitReport, resolveCatalog, findInstalledPackage, packCli, serveConsoleFor, catalogDefaults, CATALOG_INDEX_PACKAGE } from '@volter/world-runtime';
-import { readFileSync, realpathSync } from 'node:fs';
+import { realpathSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { spawn, spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
@@ -15,7 +15,7 @@ import { forgetPlatform, forgetToken, platformOrigin, storePlatform, storeToken,
 import { parseOriginUrl, World } from "./world.js";
 import { copyExample, examples } from "./examples.js";
 import { waitForServeShutdown } from "./serve-shutdown.js";
-import { startUpdateCheck } from "./update-notice.js";
+import { currentVersion, startUpdateCheck } from "./update-notice.js";
 import { withoutVaultSignIn } from '@volter/world-runtime';
 /** Open a URL in the person's browser; a machine without one only loses the convenience. */
 function openInBrowser(url) {
@@ -1095,16 +1095,7 @@ async function offerAgents() {
 }
 /** This package's version, for the MCP server's handshake. */
 function ownVersion() {
-    // src/cli.ts in the repository, dist/src/cli.js in the published package: the package's manifest is one or two up
-    for (const up of ['../package.json', '../../package.json']) {
-        try {
-            const m = JSON.parse(readFileSync(fileURLToPath(new URL(up, import.meta.url)), 'utf8'));
-            if (m.name === '@volter/world' && m.version)
-                return m.version;
-        }
-        catch { /* not there */ }
-    }
-    return '0.0.0';
+    return currentVersion() ?? '0.0.0';
 }
 async function main() {
     const [noun, verb, ...args] = process.argv.slice(2);

package/dist/src/mcp.js

@@ -29,9 +29,9 @@ function volter(args, dir, timeoutSeconds = 600) {
     });
 }
 /** A command that keeps running (the World's view, a sign-in waiting for approval): started once, answered as soon as
- *  its first lines say what the agent needs, left running for as long as this server runs. */
+ *  its announcement says what the agent needs, left running for as long as this server runs. */
 const background = new Map();
-function startBackground(key, args, dir, ready, seconds = 60) {
+function startBackground(key, args, dir, ready, seconds = 60, incompleteCode = 0) {
     background.get(key)?.kill();
     background.delete(key);
     return new Promise((done) => {
@@ -44,15 +44,23 @@ function startBackground(key, args, dir, ready, seconds = 60) {
             clearTimeout(timer);
             done({ code, output });
         } };
-        const take = (d) => { output += d.toString(); if (ready.test(output))
+        const take = (d) => { output += d.toString(); if (typeof ready === 'function' ? ready(output) : ready.test(output))
             answer(0); };
         child.stdout.on('data', take);
         child.stderr.on('data', take);
         child.on('error', (e) => { output += e.message; answer(1); });
-        child.on('close', (code) => { background.delete(key); answer(code ?? 1); });
-        const timer = setTimeout(() => answer(0), seconds * 1000);
+        child.on('close', (code) => { background.delete(key); answer(code === 0 ? incompleteCode : code ?? 1); });
+        const timer = setTimeout(() => answer(incompleteCode), seconds * 1000);
     });
 }
+/** cli.ts finishes the access announcement after the runtime's initial viewing/console lines. */
+function viewAnnouncementComplete(output) {
+    if (/(?:^|\n)apps[ \t]+/.test(output)) {
+        // The local-origin announcement ends with its browser guidance, after any missing-console notice.
+        return /(?:^|\n)\(the World opens at its own \*\.localhost origin;[^\r\n]*\)\r?\n/.test(output);
+    }
+    return /(?:^|\n)(?:read-only view[ \t]+\S+|\(no console installed:[^\r\n]*\))\r?\n/.test(output);
+}
 /** Everything this server left running, ended: a World under a dashboard is brought down through its own command first
  *  (its state kept, its teardown recorded), then the command itself. */
 function stopAll() {
@@ -126,7 +134,7 @@ export async function serveMcp(version) {
         catch (e) {
             return fail(e);
         }
-        const r = await startBackground(`view:${root}`, ['world', 'view', '--no-open'], root, /console\s+\S+/);
+        const r = await startBackground(`view:${root}`, ['world', 'view', '--no-open'], root, viewAnnouncementComplete, 60, 1);
         return text(`${before}${r.output}`, r.code !== 0);
     });
     server.registerTool('world_log', {

package/dist/src/update-notice.d.ts

@@ -1,5 +1,5 @@
-/** This package's version, read from its own package.json. */
-export declare function currentVersion(): string;
+/** This package's version, read from its own package.json, or null when it cannot be established. */
+export declare function currentVersion(): string | null;
 /** Whether `a` is a newer release than `b` (major.minor.patch; a prerelease is not offered). */
 export declare function newer(a: string, b: string): boolean;
 /** Start the day's check if one is due, while the command runs; the returned function, called when the command is

package/dist/src/update-notice.js

@@ -7,14 +7,18 @@ import { dirname, join } from 'node:path';
 import { credentialsPath } from "./credentials.js";
 const DAY = 86_400_000;
 const REGISTRY = 'https://registry.npmjs.org/@volter/world/latest';
-/** This package's version, read from its own package.json. */
+/** This package's version, read from its own package.json, or null when it cannot be established. */
 export function currentVersion() {
-    try {
-        return JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version ?? '0.0.0';
-    }
-    catch {
-        return '0.0.0';
+    // src/update-notice.ts in the repository, dist/src/update-notice.js in the published package
+    for (const up of ['../package.json', '../../package.json']) {
+        try {
+            const m = JSON.parse(readFileSync(new URL(up, import.meta.url), 'utf8'));
+            if (m.name === '@volter/world' && typeof m.version === 'string' && m.version)
+                return m.version;
+        }
+        catch { /* not there or unreadable */ }
     }
+    return null;
 }
 /** Whether `a` is a newer release than `b` (major.minor.patch; a prerelease is not offered). */
 export function newer(a, b) {
@@ -33,6 +37,9 @@ export function newer(a, b) {
 export function startUpdateCheck(args, env = process.env) {
     if (env.VOLTER_NO_UPDATE_NOTIFIER || env.CI || args.includes('--json') || !process.stderr.isTTY)
         return async () => undefined;
+    const here = currentVersion();
+    if (!here)
+        return async () => undefined;
     const path = join(dirname(credentialsPath()), 'update-check.json');
     let kept = null;
     try {
@@ -53,7 +60,6 @@ export function startUpdateCheck(args, env = process.env) {
         : Promise.resolve(kept?.latest ?? null);
     return async () => {
         const latest = await Promise.race([check, new Promise((r) => setTimeout(() => r(null), 800))]);
-        const here = currentVersion();
         if (latest && newer(latest, here))
             process.stderr.write(`\nvolter ${latest} is out (you have ${here}): npm install -g @volter/world\n`);
     };

package/examples/customer-onboarding/README.md

@@ -13,7 +13,7 @@ You need Node 22.6+, npm and registry access during installation. The browser pa
 Copy this starter into a new folder:
 
 ```console
-$ npx @volter/world@3.0.164 example customer-onboarding --dir onboarding
+$ npx @volter/world@3.0.166 example customer-onboarding --dir onboarding
 $ cd onboarding
 $ npm install
 ```
@@ -41,6 +41,8 @@ $ ./node_modules/.bin/volter world log
 
 Read the customer returned by Stripe, the signup row returned by SQL and the email returned by Resend. `completion: complete` means delivery was observed, not merely that a send request was accepted. Opaque IDs can differ between fresh Worlds; customer identity, stored fields and delivery status are the useful outcomes.
 
+The SQL `completion` column retains the last send result. `run.mjs read` and the browser combine that saved row with Resend's current `last_event` to derive `complete` or `partial-email-bounced`. Observing delivery leaves the SQL row unchanged.
+
 ## Observe two different failures
 
 A refusing recipient's mail server creates a bounce after the send was accepted:
@@ -83,16 +85,29 @@ Then start the app through the World:
 $ ./node_modules/.bin/volter world run -- node server.mjs
 ```
 
-Open the printed app URL in your browser. Submit a signup, advance the World clock in another terminal and reload. The page shows the completion state and full stored outcome. Its server registers its app URL with the World after listening; consumers can discover it with `world app-url`.
+The server registers its app URL with the World after listening. In another terminal, from the same application folder, read that endpoint with the installed operator command:
+
+```console
+$ ./node_modules/.bin/volter-world app-url onboarding --root .
+```
+
+`onboarding` is the World name selected by the init command above; use your current branch's name if you have branched. `--root .` selects this application's World. Open the returned URL or the server's printed app URL in your browser. Submit a signup, advance the World clock in another terminal and reload. The page shows the completion state and full stored outcome. [The CLI reference](https://world.volter.ai/docs/reference/cli.html#the-world-itself) describes endpoint discovery and registration.
+
+To have the World start and stop the app with its services, declare `server.mjs` as a process service using [run a full stack](https://world.volter.ai/docs/guides/run-a-full-stack.html#the-app-as-a-service). This server honors the World-assigned `PORT`; use `/` as its HTTP readiness path. The manual command above chooses an available port when `PORT` is absent.
 
-To open the World dashboard, stop the app with Ctrl-C first, then switch the owned compute to the viewer:
+To open the World dashboard, switch the owned compute to the viewer. If you started the app
+manually with `world run`, stop that app with Ctrl-C first. If you declared it as a process
+service, the `down` command below stops it with the World's other services:
 
 ```console
 $ ./node_modules/.bin/volter world down
 $ ./node_modules/.bin/volter world view --no-open
 ```
 
-The viewer prints the dashboard URL and keeps running. Start `world run -- node server.mjs` in a second terminal if you want the application alongside it. Open **Stripe** under **Records**, then select the customer to inspect its name, email and stored ID. Open **Resend** to inspect the accepted email and delivery event. **Board** opens the vendor pages declared by the installed twin; its root workspace may cover settings rather than customers. Provisioning remains in full history even when hidden from the business-activity view. Read the application's SQL completion record with `run.mjs read` or its browser page.
+The viewer prints the dashboard URL and keeps running. In manual app mode, start
+`world run -- node server.mjs` in a second terminal if you want the application alongside it.
+With a declared process service, the viewer starts the app as part of the World; no second
+app command is needed. Open **Stripe** under **Records**, then select the customer to inspect its name, email and stored ID. Open **Resend** to inspect the accepted email and delivery event. **Board** opens the vendor pages declared by the installed twin; its root workspace may cover settings rather than customers. Provisioning remains in full history even when hidden from the business-activity view. Read the application's combined signup, customer and delivery result with `run.mjs read` or its browser page.
 
 Stop app consumers before stopping the viewer. `down` retains vendor and declared application state. [Resume](https://world.volter.ai/docs/guides/resume-a-world.html) explains continuing it; [demo a workflow](https://world.volter.ai/docs/guides/demo-a-workflow.html) uses this same application for a repeatable baseline, refusal and retry. Reset only your disposable example World; it discards that branch's work.
 

package/examples/customer-onboarding/package.json

@@ -11,11 +11,12 @@
     "pg": "8.16.3"
   },
   "devDependencies": {
-    "@volter/world": "3.0.164",
-    "@volter/world-core": "3.0.154",
-    "@volter/world-runtime": "3.0.162",
-    "@volter/world-console": "3.0.150",
+    "@volter/world": "3.0.166",
+    "@volter/world-core": "3.0.155",
+    "@volter/world-runtime": "3.0.163",
+    "@volter/world-console": "3.0.151",
     "@volter/twin-stripe": "3.0.2",
-    "@volter/twin-resend": "1.0.1"
+    "@volter/twin-resend": "1.0.1",
+    "@volter/world-ui": "1.0.155"
   }
 }

package/examples/customer-onboarding/server.mjs

@@ -25,7 +25,7 @@ const server = createServer(async (request, response) => {
     response.end(`<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width"><title>Customer onboarding</title><link rel="stylesheet" href="/brand/tokens.css"><link rel="stylesheet" href="/style.css"><main><header><img src="/brand/world.svg" width="32" height="32" alt="Volter World"><h1>Customer onboarding</h1></header><p>Create a customer, save an application row and request a welcome email.</p><form method="post" action="/signup"><label>Name <input name="name" value="Ada" required></label><label>Email <input name="email" type="email" value="owner@world.test" required></label><button>Create account</button></form><h2>Accounts</h2><p>Reload after advancing the World clock to observe delivery. A refused email leaves the customer and application row intact.</p>${rows.map(r => `<article><h3>${escape(r.name)}</h3><p>${escape(r.email)} · <strong>${escape(r.completion)}</strong></p><p>Stripe: <code>${escape(r.customer_id)}</code> · Email: <code>${escape(r.email_id ?? 'not accepted')}</code></p><details><summary>Stored outcome</summary><pre>${escape(JSON.stringify(r, null, 2))}</pre></details></article>`).join('') || '<p>No customers yet.</p>'}</main></html>`);
   } catch (error) { response.writeHead(500, { 'Content-Type': 'text/plain' }); response.end(error.message); }
 });
-await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
+await new Promise(resolve => server.listen(Number(process.env.PORT ?? 0), '127.0.0.1', resolve));
 const url = `http://127.0.0.1:${server.address().port}`;
 setAppUrl(process.env.VOLTER_WORLD, url, { root: process.cwd() });
 console.log(`Customer onboarding ${url}`);

package/examples/integration-branches/README.md

@@ -13,7 +13,7 @@ Give two workers the same Stripe baseline, let them change different existing cu
 Use an empty parent folder. Create the baseline starter there:
 
 ```console
-$ npx @volter/world@3.0.164 example integration-branches --dir baseline
+$ npx @volter/world@3.0.166 example integration-branches --dir baseline
 $ cd baseline
 $ npm install
 $ ./node_modules/.bin/volter world init --name baseline --twins stripe
@@ -38,9 +38,9 @@ The stopped baseline retains its history and can supply local path remotes. Defa
 Create three more copies in the same parent folder:
 
 ```console
-$ npx @volter/world@3.0.164 example integration-branches --dir integration
-$ npx @volter/world@3.0.164 example integration-branches --dir worker-a
-$ npx @volter/world@3.0.164 example integration-branches --dir worker-b
+$ npx @volter/world@3.0.166 example integration-branches --dir integration
+$ npx @volter/world@3.0.166 example integration-branches --dir worker-a
+$ npx @volter/world@3.0.166 example integration-branches --dir worker-b
 ```
 
 In `integration`, then `worker-a`, then `worker-b`, install dependencies and initialize with the folder's name. Before a first boot or app write, link and pull the baseline:

package/examples/integration-branches/package.json

@@ -9,10 +9,11 @@
     "stripe": "17.7.0"
   },
   "devDependencies": {
-    "@volter/world": "3.0.164",
-    "@volter/world-core": "3.0.154",
-    "@volter/world-runtime": "3.0.162",
-    "@volter/world-console": "3.0.150",
-    "@volter/twin-stripe": "3.0.2"
+    "@volter/world": "3.0.166",
+    "@volter/world-core": "3.0.155",
+    "@volter/world-runtime": "3.0.163",
+    "@volter/world-console": "3.0.151",
+    "@volter/twin-stripe": "3.0.2",
+    "@volter/world-ui": "1.0.155"
   }
 }

package/examples/workplace-agent/README.md

@@ -19,7 +19,7 @@ A catalog page may select a newer default. Keep this example's manifest and inst
 together; its recorded workflow does not establish behavior for a different release.
 
 ```console
-$ npx @volter/world@3.0.164 example workplace-agent --dir workplace
+$ npx @volter/world@3.0.166 example workplace-agent --dir workplace
 $ cd workplace
 $ npm install
 $ ./node_modules/.bin/volter world init --name workplace --twins github,linear,slack

package/examples/workplace-agent/package.json

@@ -11,12 +11,13 @@
     "@slack/web-api": "7.19.0"
   },
   "devDependencies": {
-    "@volter/world": "3.0.164",
-    "@volter/world-core": "3.0.154",
-    "@volter/world-runtime": "3.0.162",
-    "@volter/world-console": "3.0.150",
+    "@volter/world": "3.0.166",
+    "@volter/world-core": "3.0.155",
+    "@volter/world-runtime": "3.0.163",
+    "@volter/world-console": "3.0.151",
     "@volter/twin-github": "3.0.9",
     "@volter/twin-linear": "3.0.5",
-    "@volter/twin-slack": "3.0.8"
+    "@volter/twin-slack": "3.0.8",
+    "@volter/world-ui": "1.0.155"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world",
-  "version": "3.0.164",
+  "version": "3.0.166",
   "description": "Run your app against a world of twins. `World` and `Repo` — one method per verb: init, up, run, log, diff, reset, branch, checkout, clone, fetch, changeset, push — and the `volter` command, one client of them.",
   "keywords": [
     "volter",
@@ -31,12 +31,12 @@
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.1",
-    "@volter/world-core": "3.0.154",
-    "@volter/world-runtime": "3.0.162",
+    "@volter/world-core": "3.0.155",
+    "@volter/world-runtime": "3.0.163",
     "zod": "^4.6.5"
   },
   "peerDependencies": {
-    "@volter/world-console": "3.0.150"
+    "@volter/world-console": "3.0.151"
   },
   "peerDependenciesMeta": {
     "@volter/world-console": {
@@ -44,7 +44,7 @@
     }
   },
   "devDependencies": {
-    "@volter/world-console": "3.0.150"
+    "@volter/world-console": "3.0.151"
   },
   "bin": {
     "volter": "dist/src/cli.js"

package/src/agents.ts

@@ -31,9 +31,8 @@ export function skillSource(): string {
   throw new Error('the volter-world skill is not in this installation (skills/volter-world)');
 }
 
-/** How an agent starts the server: `volter mcp` when the command is on PATH, else this installation by its path. */
+/** Start this installation's server under this runtime; PATH may contain another version of `volter`. */
 export function mcpCommand(): { command: string; args: string[] } {
-  if (which('volter')) return { command: 'volter', args: ['mcp'] };
   const cli = fileURLToPath(new URL(`./cli${import.meta.url.endsWith('.ts') ? '.ts' : '.js'}`, import.meta.url));
   return { command: process.execPath, args: [cli, 'mcp'] };
 }

package/src/cli.ts

@@ -16,7 +16,7 @@ import { forgetPlatform, forgetToken, platformOrigin, requireToken, storePlatfor
 import { parseOriginUrl, World } from './world.ts';
 import { copyExample, examples } from './examples.ts';
 import { waitForServeShutdown } from './serve-shutdown.ts';
-import { startUpdateCheck } from './update-notice.ts';
+import { currentVersion, startUpdateCheck } from './update-notice.ts';
 import type { ViewConsole } from '@volter/world-runtime';
 import { withoutVaultSignIn } from '@volter/world-runtime';
 
@@ -814,11 +814,7 @@ async function offerAgents(): Promise<void> {
 
 /** This package's version, for the MCP server's handshake. */
 function ownVersion(): string {
-  // src/cli.ts in the repository, dist/src/cli.js in the published package: the package's manifest is one or two up
-  for (const up of ['../package.json', '../../package.json']) {
-    try { const m = JSON.parse(readFileSync(fileURLToPath(new URL(up, import.meta.url)), 'utf8')) as { name?: string; version?: string }; if (m.name === '@volter/world' && m.version) return m.version; } catch { /* not there */ }
-  }
-  return '0.0.0';
+  return currentVersion() ?? '0.0.0';
 }
 
 async function main(): Promise<void> {

package/src/mcp.ts

@@ -31,22 +31,31 @@ function volter(args: string[], dir: string, timeoutSeconds = 600): Promise<Ran>
 }
 
 /** A command that keeps running (the World's view, a sign-in waiting for approval): started once, answered as soon as
- *  its first lines say what the agent needs, left running for as long as this server runs. */
+ *  its announcement says what the agent needs, left running for as long as this server runs. */
 const background = new Map<string, ChildProcess>();
-function startBackground(key: string, args: string[], dir: string, ready: RegExp, seconds = 60): Promise<Ran> {
+function startBackground(key: string, args: string[], dir: string, ready: RegExp | ((output: string) => boolean), seconds = 60, incompleteCode = 0): Promise<Ran> {
   background.get(key)?.kill(); background.delete(key);
   return new Promise((done) => {
     const child = spawn(process.execPath, [CLI, ...args], { cwd: dir, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'], env: process.env });
     background.set(key, child);
     let output = ''; let answered = false;
     const answer = (code: number): void => { if (!answered) { answered = true; clearTimeout(timer); done({ code, output }); } };
-    const take = (d: Buffer): void => { output += d.toString(); if (ready.test(output)) answer(0); };
+    const take = (d: Buffer): void => { output += d.toString(); if (typeof ready === 'function' ? ready(output) : ready.test(output)) answer(0); };
     child.stdout!.on('data', take); child.stderr!.on('data', take);
     child.on('error', (e) => { output += e.message; answer(1); });
-    child.on('close', (code) => { background.delete(key); answer(code ?? 1); });
-    const timer = setTimeout(() => answer(0), seconds * 1000);
+    child.on('close', (code) => { background.delete(key); answer(code === 0 ? incompleteCode : code ?? 1); });
+    const timer = setTimeout(() => answer(incompleteCode), seconds * 1000);
   });
 }
+
+/** cli.ts finishes the access announcement after the runtime's initial viewing/console lines. */
+function viewAnnouncementComplete(output: string): boolean {
+  if (/(?:^|\n)apps[ \t]+/.test(output)) {
+    // The local-origin announcement ends with its browser guidance, after any missing-console notice.
+    return /(?:^|\n)\(the World opens at its own \*\.localhost origin;[^\r\n]*\)\r?\n/.test(output);
+  }
+  return /(?:^|\n)(?:read-only view[ \t]+\S+|\(no console installed:[^\r\n]*\))\r?\n/.test(output);
+}
 /** Everything this server left running, ended: a World under a dashboard is brought down through its own command first
  *  (its state kept, its teardown recorded), then the command itself. */
 function stopAll(): void {
@@ -111,7 +120,7 @@ export async function serveMcp(version: string): Promise<void> {
     const root = here(dir);
     let before = '';
     try { const s = World.open({ root }).status(); if (s.running && !s.served) { const down = await volter(['world', 'down'], root); if (down.code !== 0) return ran(down); before = `${down.output.trim()} (state kept; the dashboard runs it now)\n`; } } catch (e) { return fail(e); }
-    const r = await startBackground(`view:${root}`, ['world', 'view', '--no-open'], root, /console\s+\S+/);
+    const r = await startBackground(`view:${root}`, ['world', 'view', '--no-open'], root, viewAnnouncementComplete, 60, 1);
     return text(`${before}${r.output}`, r.code !== 0);
   });
 

package/src/update-notice.ts

@@ -11,9 +11,16 @@ const REGISTRY = 'https://registry.npmjs.org/@volter/world/latest';
 
 type Checked = { checkedAt: string; latest: string | null };
 
-/** This package's version, read from its own package.json. */
-export function currentVersion(): string {
-  try { return (JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')) as { version?: string }).version ?? '0.0.0'; } catch { return '0.0.0'; }
+/** This package's version, read from its own package.json, or null when it cannot be established. */
+export function currentVersion(): string | null {
+  // src/update-notice.ts in the repository, dist/src/update-notice.js in the published package
+  for (const up of ['../package.json', '../../package.json']) {
+    try {
+      const m = JSON.parse(readFileSync(new URL(up, import.meta.url), 'utf8')) as { name?: string; version?: string };
+      if (m.name === '@volter/world' && typeof m.version === 'string' && m.version) return m.version;
+    } catch { /* not there or unreadable */ }
+  }
+  return null;
 }
 
 /** Whether `a` is a newer release than `b` (major.minor.patch; a prerelease is not offered). */
@@ -28,6 +35,8 @@ export function newer(a: string, b: string): boolean {
  *  done, waits a moment at most for it and prints the notice when there is one. Off, it does nothing and asks nothing. */
 export function startUpdateCheck(args: string[], env: NodeJS.ProcessEnv = process.env): () => Promise<void> {
   if (env.VOLTER_NO_UPDATE_NOTIFIER || env.CI || args.includes('--json') || !process.stderr.isTTY) return async () => undefined;
+  const here = currentVersion();
+  if (!here) return async () => undefined;
   const path = join(dirname(credentialsPath()), 'update-check.json');
   let kept: Checked | null = null;
   try { if (existsSync(path)) kept = JSON.parse(readFileSync(path, 'utf8')) as Checked; } catch { kept = null; }
@@ -38,7 +47,6 @@ export function startUpdateCheck(args: string[], env: NodeJS.ProcessEnv = proces
     : Promise.resolve(kept?.latest ?? null);
   return async () => {
     const latest = await Promise.race([check, new Promise<null>((r) => setTimeout(() => r(null), 800))]);
-    const here = currentVersion();
     if (latest && newer(latest, here)) process.stderr.write(`\nvolter ${latest} is out (you have ${here}): npm install -g @volter/world\n`);
   };
 }