@volter/world 2.0.58 → 3.0.1

package/README.md

@@ -22,6 +22,6 @@ console.log(world.log());
 await world.down();
 ```
 
-- [Getting started](https://github.com/volter-ai/twin/blob/main/docs/getting-started.md)
-- [CLI reference](https://github.com/volter-ai/twin/blob/main/docs/reference/cli.md)
-- [SDK reference](https://github.com/volter-ai/twin/blob/main/docs/reference/sdk.md)
+- [Getting started](https://github.com/volter-ai/twin-world/blob/main/docs/getting-started.md)
+- [CLI reference](https://github.com/volter-ai/twin-world/blob/main/docs/reference/cli.md)
+- [SDK reference](https://github.com/volter-ai/twin-world/blob/main/docs/reference/sdk.md)

package/dist/skills/volter-world/AGENTS.md

@@ -7,13 +7,13 @@ environment injection, a Node preload and a scoped HTTPS proxy route configured
 The state model is **Neon for every SaaS**: a log, checkpoints and branches over a parent position.
 Git-inspired verbs describe operations; there is no staging or commit step. Push moves entries
 between Worlds. Deploy performs them against a vendor at a real-system root under its policy.
-The canonical [model](https://github.com/volter-ai/twin/blob/main/docs/concepts/the-model.md),
-[lifecycle](https://github.com/volter-ai/twin/blob/main/docs/concepts/worlds.md) and
-[CLI reference](https://github.com/volter-ai/twin/blob/main/docs/reference/cli.md) own the details.
+The canonical [model](https://github.com/volter-ai/twin-world/blob/main/docs/concepts/the-model.md),
+[lifecycle](https://github.com/volter-ai/twin-world/blob/main/docs/concepts/worlds.md) and
+[CLI reference](https://github.com/volter-ai/twin-world/blob/main/docs/reference/cli.md) own the details.
 
 ## Set up a World for an app
 
-In the app's folder (the [guide](https://github.com/volter-ai/twin/blob/main/docs/guides/use-with-a-coding-agent.md)):
+In the app's folder (the [guide](https://github.com/volter-ai/twin-world/blob/main/docs/guides/use-with-a-coding-agent.md)):
 
 ```bash
 npm install -g @volter/world     # once; `volter agents install` then adds this skill and the MCP server to your agents

package/dist/skills/volter-world/SKILL.md

@@ -10,5 +10,5 @@ operator instruction source shipped with this skill: setting a World up for an a
 to a platform, the `volter mcp` tools, and the lifecycle distinction between the product command
 `volter world` and the explicit operator command `volter-world`.
 
-The [documentation map](https://github.com/volter-ai/twin/blob/main/docs/README.md) links the
+The [documentation map](https://github.com/volter-ai/twin-world/blob/main/docs/README.md) links the
 canonical model, task guides and command reference. Do not maintain a second copy here.

package/dist/src/agents.js

@@ -84,7 +84,7 @@ const writeJson = (path, value) => writeAtomic(path, `${JSON.stringify(value, nu
 /** A command run as itself; on Windows, where `claude` is a .cmd that runs only in cmd, one line to cmd with each argument
  *  quoted (a path with a space stays one argument), as cross-spawn does. */
 const runTool = (bin, args) => process.platform === 'win32'
-    ? spawnSync(process.env.ComSpec ?? 'cmd.exe', ['/d', '/s', '/c', `"${[bin, ...args].map((a) => `"${a.replace(/"/g, '""')}"`).join(' ')}"`], { windowsHide: true, encoding: 'utf8', windowsVerbatimArguments: true })
+    ? spawnSync(process.env.ComSpec ?? 'cmd.exe', ['/d', '/s', '/c', `"${[bin, ...args].map((a) => `"${a.replaceAll('"', '""')}"`).join(' ')}"`], { windowsHide: true, encoding: 'utf8', windowsVerbatimArguments: true })
     : spawnSync(bin, args, { windowsHide: true, encoding: 'utf8' });
 const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
 /** Our entry under `key` in a JSON config's server map: added, or already there; someone else's `volter` is left alone. */

package/dist/src/cli.d.ts

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-export declare const HELP = "volter \u2014 run your app against a world of twins\n\nworld  \u2014 the twins your app needs, running together (the world of the current directory)\n  volter world init [--install] [--name <world>] [--allow-unknown]   detect the app's vendors (installing their twins when none are), write .volter/world.json\n  volter world up [--sandbox] [--no-seed]                start the twins on this branch (loads the default data the first time)\n  volter world run [--verbose] -- <command...>           run the app or its tests inside the world\n  volter world activate                                  eval \"$(volter world activate)\": vendor CLIs and curl in this shell reach the twins\n  volter world shell                                     a subshell with the world active\n  volter world init --bare <org>/<world> --twins a,b      a world with no app: a shared world for a team, or one standing in for a vendor\n  volter world serve [--port <p>] [--console-port <c>] [--origin <url>]   serve this world on a URL under /<org>/<world>/ for apps; prints the token and the console (on loopback: view's front, no token in the browser)\n  volter world view [--port <p>] [--host <h>] [--no-open] [--no-origins] [--origin <url>]   step into this world in a browser: its twins' own UIs, timeline, clock, branches (a non-loopback --host serves them on one origin)\n  volter world console [<https://host/org/world>] [--port <p>]  the console on this machine for a World served elsewhere (default: this world's origin); needs @volter/world-console\n  volter world status                                    world, branch, origin, unpushed changes, what is running\n  volter world log [--receipts] [--json]                 every write the app made; --receipts adds each change's receipt\n  volter world diff [--json]                             what changed since the default data (or the last mark)\n  volter world seed                                      load the default data\n  volter world reset                                     back to the default data\n  volter world down [--purge]                            stop the twins (--purge forgets this branch's state)\n  volter world branch [<name>]                           list branches, or make one from here and check it out\n  volter world checkout <name>                           switch branches\n  volter world replay <changeset> --into <branch>        feed a changeset's changes into another branch's twins\n  volter world clock show | set <iso> | advance <N s|m|h|d> | shift <N s|m|h|d> | clear   the world's clock: set, not observed\n  volter world clone <url> --token <token> [--admin-token <t>]   connect this world to a remote and fetch its history (the admin token copies the whole tree at once)\n  volter world fetch                                     what the remote observed since the last fetch\n  volter world origin                                    where this world clones from and pushes to\n  volter world changeset [<name>] -m \"<message>\"         cut the unpushed changes into a reviewable changeset\n  volter world pull [--token <token>]                    fetch, then move this branch onto what came in (git's pull)\n  volter world push [<name>] [--token <token>] [--force] push to the remote, which deploys and answers with receipts\n  volter world rebase [<changeset>]                      rebase this branch onto its moved base, or a changeset onto the moved mirror\n  volter world verify <changeset>                        run the world's checks over a changeset and record the result\n  volter world approve <changeset> --as <principal>      sign a changeset's current hash\n  volter world deploy [<changeset>]                      perform landed changes against each twin's root, by its policy\n\ntwin   \u2014 one twin: in this world, or on its own\n  volter twin <vendor>                                   the twin's URL, root, deploy policy, whether a credential is sealed\n  volter twin <vendor> root <url> [--deploy auto|gated|hold] [--scope <path>]   the vendor's real account behind this twin (--none clears it)\n  volter twin <vendor> credential                        seal a credential read from stdin beside the world; never readable back\n  volter twin <vendor> refresh                           observe the root now\n  volter twin <vendor> serve [--port <p>] [--read-only]  serve the twin; your SDK talks to it at http://127.0.0.1:<p>\n  volter twin <vendor> mirror [--port <p>]               the twin's UI mirror\n  volter twin <vendor> conformance                       check the twin against the vendor's spec\n\nagents \u2014 your coding agent, driving the same verbs\n  volter agents install [--claude] [--cursor] [--vscode] [--codex] [--yes]   put the volter-world skill and the MCP server into the agents found here\n  volter mcp                                             the MCP server (stdio) an agent starts: the verbs above as tools\n\nremote \u2014 the worlds this one pushes to and fetches from, by name\n  volter login <platform url> [--token <personal token>]  sign the CLI into the hosted platform: approve it in the browser (or a token made under Account, for CI)\n  volter whoami                                          the platform the CLI is signed into, as whom, and its orgs\n  volter logout                                          revoke the CLI's token at the platform and forget it here\n  volter remote add <name> <url|path|org/world> [--token <token>] [--create]  name a remote; org/world (or world, in one org) resolves through the platform you logged into; --create makes it there from this world's twins\n  volter open [<org>/<world>] [--no-open]                a World's dashboard: a hosted one through the platform, else this world's (as view)\n  volter completion bash|zsh|fish|powershell             print a completion script for your shell\n  volter remote remove <name>                            forget it\n  volter remote list                                     every remote, with its URL and whether a token is stored\n  (the hosting product's serve answers here for one release: volter remote serve)\n\n  --world <dir>    the world root, when the cwd is not inside it\n  --branch <name>  act on that branch instead of the checked-out one\n  --json           machine-readable output where offered\n";
+export declare const HELP = "volter \u2014 run your app against a world of twins\n\nworld  \u2014 the twins your app needs, running together (the world of the current directory)\n  volter world init [--install] [--name <world>] [--allow-unknown]   detect the app's vendors (installing their twins when none are), write .volter/world.json\n  volter world up [--sandbox] [--no-seed]                start the twins on this branch (loads the default data the first time)\n  volter world run [--verbose] -- <command...>           run the app or its tests inside the world\n  volter world activate                                  eval \"$(volter world activate)\": vendor CLIs and curl in this shell reach the twins\n  volter world shell                                     a subshell with the world active\n  volter world init --bare <org>/<world> --twins a,b      a world with no app: a shared world for a team, or one standing in for a vendor\n  volter world serve [--port <p>] [--console-port <c>] [--origin <url>]   serve this world on a URL under /<org>/<world>/ for apps; prints the token and the console (on loopback: view's front, no token in the browser)\n  volter world view [--port <p>] [--host <h>] [--no-open] [--no-origins] [--origin <url>]   step into this world in a browser: its twins' own UIs, timeline, clock, branches (a non-loopback --host serves them on one origin)\n  volter world console [<https://host/org/world>] [--port <p>]  the console on this machine for a World served elsewhere (default: this world's origin); needs @volter/world-console\n  volter world status                                    world, branch, origin, unpushed changes, what is running\n  volter world log [--receipts] [--json]                 every write the app made; --receipts adds each change's receipt\n  volter world diff [--json]                             what changed since the default data (or the last mark)\n  volter world seed                                      load the default data\n  volter world reset                                     back to the default data\n  volter world down [--purge]                            stop the twins (--purge forgets this branch's state)\n  volter world branch [<name>]                           list branches, or make one from here and check it out\n  volter world checkout <name>                           switch branches\n  volter world replay <changeset> --into <branch>        feed a changeset's changes into another branch's twins\n  volter world clock show | set <iso> | advance <N s|m|h|d> | shift <N s|m|h|d> | clear   the world's clock: set, not observed\n  volter world clone <url> --token <token> [--admin-token <t>]   connect this world to a remote and fetch its history (the admin token copies the whole tree at once)\n  volter world fetch                                     what the remote observed since the last fetch\n  volter world origin                                    where this world clones from and pushes to\n  volter world changeset [<name>] -m \"<message>\"         cut the unpushed changes into a reviewable changeset\n  volter world pull [--token <token>]                    fetch, then move this branch onto what came in (git's pull)\n  volter world push [<name>] [--token <token>] [--force] push to the remote, which deploys and answers with receipts\n  volter world rebase [<changeset>]                      rebase this branch onto its moved base, or a changeset onto the moved remote\n  volter world verify <changeset>                        run the world's checks over a changeset and record the result\n  volter world approve <changeset> --as <principal>      sign a changeset's current hash\n  volter world deploy [<changeset>]                      perform landed changes against each twin's root, by its policy\n\ntwin   \u2014 one twin: in this world, or on its own\n  volter twin <vendor>                                   the twin's URL, root, deploy policy, whether a credential is sealed\n  volter twin <vendor> root <url> [--deploy auto|gated|hold] [--scope <path>]   the vendor's real account behind this twin (--none clears it)\n  volter twin <vendor> credential                        seal a credential read from stdin beside the world; never readable back\n  volter twin <vendor> refresh                           observe the root now\n  volter twin <vendor> serve [--port <p>] [--read-only]  serve the twin; your SDK talks to it at http://127.0.0.1:<p>\n\nagents \u2014 your coding agent, driving the same verbs\n  volter agents install [--claude] [--cursor] [--vscode] [--codex] [--yes]   put the volter-world skill and the MCP server into the agents found here\n  volter mcp                                             the MCP server (stdio) an agent starts: the verbs above as tools\n\nremote \u2014 the worlds this one pushes to and fetches from, by name\n  volter login <platform url> [--token <personal token>]  sign the CLI into the hosted platform: approve it in the browser (or a token made under Account, for CI)\n  volter whoami                                          the platform the CLI is signed into, as whom, and its orgs\n  volter logout                                          revoke the CLI's token at the platform and forget it here\n  volter remote add <name> <url|path|org/world> [--token <token>] [--create]  name a remote; org/world (or world, in one org) resolves through the platform you logged into; --create makes it there from this world's twins\n  volter open [<org>/<world>] [--no-open]                a World's dashboard: a hosted one through the platform, else this world's (as view)\n  volter completion bash|zsh|fish|powershell             print a completion script for your shell\n  volter remote remove <name>                            forget it\n  volter remote list                                     every remote, with its URL and whether a token is stored\n  (the hosting product's serve answers here for one release: volter remote serve)\n\n  --world <dir>    the world root, when the cwd is not inside it\n  --branch <name>  act on that branch instead of the checked-out one\n  --json           machine-readable output where offered\n  --version        the command's version\n";

package/dist/src/cli.js

@@ -64,7 +64,7 @@ world  — the twins your app needs, running together (the world of the current
   volter world changeset [<name>] -m "<message>"         cut the unpushed changes into a reviewable changeset
   volter world pull [--token <token>]                    fetch, then move this branch onto what came in (git's pull)
   volter world push [<name>] [--token <token>] [--force] push to the remote, which deploys and answers with receipts
-  volter world rebase [<changeset>]                      rebase this branch onto its moved base, or a changeset onto the moved mirror
+  volter world rebase [<changeset>]                      rebase this branch onto its moved base, or a changeset onto the moved remote
   volter world verify <changeset>                        run the world's checks over a changeset and record the result
   volter world approve <changeset> --as <principal>      sign a changeset's current hash
   volter world deploy [<changeset>]                      perform landed changes against each twin's root, by its policy
@@ -75,8 +75,6 @@ twin   — one twin: in this world, or on its own
   volter twin <vendor> credential                        seal a credential read from stdin beside the world; never readable back
   volter twin <vendor> refresh                           observe the root now
   volter twin <vendor> serve [--port <p>] [--read-only]  serve the twin; your SDK talks to it at http://127.0.0.1:<p>
-  volter twin <vendor> mirror [--port <p>]               the twin's UI mirror
-  volter twin <vendor> conformance                       check the twin against the vendor's spec
 
 agents — your coding agent, driving the same verbs
   volter agents install [--claude] [--cursor] [--vscode] [--codex] [--yes]   put the volter-world skill and the MCP server into the agents found here
@@ -96,6 +94,7 @@ remote — the worlds this one pushes to and fetches from, by name
   --world <dir>    the world root, when the cwd is not inside it
   --branch <name>  act on that branch instead of the checked-out one
   --json           machine-readable output where offered
+  --version        the command's version
 `;
 function flag(args, name) { return args.includes(name); }
 function value(args, name) {
@@ -236,6 +235,17 @@ async function worldCommand(verb, args) {
             const command = afterDashes(args);
             if (command.length === 0)
                 throw new Error('volter world run: give the command after --  (volter world run -- npm test)');
+            // a stopped World is started first, as `volter world up` does (the default data the first time), and left running
+            let running = false;
+            try {
+                running = world.instance()?.running ?? false;
+            }
+            catch { /* never started */ }
+            if (!running) {
+                process.stderr.write(`${world.name} is not running: starting it (volter world up)
+`);
+                await world.up({ seed: true });
+            }
             process.exitCode = await world.run(command, { verbose: flag(args.slice(0, args.indexOf('--')), '--verbose') });
             return;
         }
@@ -446,7 +456,7 @@ async function worldCommand(verb, args) {
                 process.exit(0); // success follows confirmed shutdown; failures reach main's error path
                 return;
             }
-            // the console mounts when it is installed beside the CLI; without it the World serves its doors and mirrors
+            // the console mounts when it is installed beside the CLI; without it the World serves its doors and the twins
             const console = await (async () => {
                 try {
                     const mod = await import('@volter/world-console');
@@ -582,7 +592,7 @@ async function worldCommand(verb, args) {
             throw new Error(`volter world: unknown verb "${verb}"\n\n${HELP}`);
     }
 }
-/** `volter twin <vendor> <verb…>`: the twin's own CLI (serve, mirror, conformance), found the way a world finds it. */
+/** `volter twin <vendor> <verb…>`: the twin's own CLI (serve), found the way a world finds it. */
 async function twinCommand(args) {
     const [vendor, ...rest] = args;
     if (!vendor || vendor.startsWith('-'))
@@ -620,7 +630,10 @@ async function twinCommand(args) {
                 out(`${vendor}  credential from ${found.from}`);
                 input = found.input;
             }
-            await world.sealTwinCredential(vendor, input);
+            const sealed = await world.sealTwinCredential(vendor, input);
+            // the root runbook: the ingest door's secret, shown once
+            if (sealed.mintedSigningSecret)
+                out(`${vendor}  signing secret ${sealed.mintedSigningSecret}  (enter it at the vendor as the webhook's secret; it is not shown again. A vendor that issues its own seals it instead: {"headers": {...}, "signingSecret": "<the vendor's>"})`);
         }
         else if (verb === 'refresh') {
             const r = await world.refreshTwin(vendor, { force: flag(rest, '--force') });
@@ -633,13 +646,16 @@ async function twinCommand(args) {
             return;
         }
         out(`${vendor}  ${t.root ? `root ${t.root.url}${t.root.scope ? `/${t.root.scope}` : ''}  deploy ${t.root.deploy}` : 'no root'}  ${t.credential ? 'credential sealed' : 'no credential'}${t.url ? `  ${t.url}` : ''}`);
+        // the root runbook: where the vendor's webhooks go
+        if (t.root)
+            out(t.ingest ? `${vendor}  ingest ${t.ingest}  (register it at the vendor as the webhook URL, with the signing secret sealed with the credential)` : `${vendor}  ingest: a served World's door (volter world serve, or a remote) is the webhook URL to register at the vendor`);
         return;
     }
     const dir = resolveCatalog(process.cwd()).packDir(vendor);
     if (dir === undefined)
         throw new Error(`No twin "${vendor}" here — \`bun add -d @volter/twin-${vendor}\`, or run from a checkout that has it`);
     if (rest.length === 0 || rest[0].startsWith('-'))
-        throw new Error(`volter twin ${vendor}: which verb? serve | mirror | conformance`);
+        throw new Error(`volter twin ${vendor}: which verb? serve | root | credential | refresh`);
     const cli = packCli(dir);
     if (cli === undefined)
         throw new Error(`No cli for twin "${vendor}" (its manifest names no bin)`);
@@ -683,7 +699,12 @@ async function loginCommand(args) {
         throw new Error(`${origin} answered ${res.status}: ${body.error ?? 'not signed in'}`);
     storeToken(origin, token);
     storePlatform(origin, undefined, body.person?.email ?? body.person?.id);
-    out(`signed in  ${origin}  as ${body.person?.email ?? body.person?.id ?? 'you'}\norgs       ${(body.orgs ?? []).map((o) => o.slug ?? o.name).join(', ') || '(none yet)'}\nnext       in your app's folder: volter world init, then volter remote add origin ${(body.orgs ?? [])[0]?.slug ?? '<org>'}/<world> --create`);
+    // a teammate's orgs already hold Worlds: the next step links one; a first person's makes one
+    const held = (body.orgs ?? []).flatMap((o) => (o.worlds ?? []).map((w) => w.name));
+    const next = held.length
+        ? `in your app's folder: volter remote add origin ${held[0]}, then volter world pull${held.length > 1 ? `  (your orgs' Worlds: ${held.slice(0, 6).join(', ')}${held.length > 6 ? ', …' : ''})` : ''}`
+        : `in your app's folder: volter world init, then volter remote add origin ${(body.orgs ?? [])[0]?.slug ?? '<org>'}/<world> --create`;
+    out(`signed in  ${origin}  as ${body.person?.email ?? body.person?.id ?? 'you'}\norgs       ${(body.orgs ?? []).map((o) => o.slug ?? o.name).join(', ') || '(none yet)'}\nnext       ${next}`);
 }
 /** `volter whoami`: which platform the command is signed into, as whom, and the orgs it reaches. */
 async function whoamiCommand() {
@@ -696,7 +717,7 @@ async function whoamiCommand() {
     }
     const res = await fetch(`${origin}/-/orgs`, { headers: { authorization: `Bearer ${token}` } }).catch(() => null);
     if (!res)
-        throw new Error(`${origin} did not answer`);
+        throw new Error(`${origin} did not answer: the platform this command is signed into is unreachable (volter login <url> signs it into another)`);
     const body = (await res.json().catch(() => ({})));
     // a token the platform no longer takes is signed out; one it takes but that may not read orgs is still signed in
     if (res.status === 403) {
@@ -1023,6 +1044,10 @@ async function dispatch(noun, verb, args) {
         out(HELP);
         return;
     }
+    if (noun === '--version' || noun === '-v' || noun === 'version') {
+        out(`volter ${ownVersion()}`);
+        return;
+    }
     switch (noun) {
         case 'world': {
             if (!verb)

package/dist/src/locate.js

@@ -4,7 +4,7 @@
 // `World.open()` start here, the way `git` starts from the nearest `.git`.
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
-import { stateDirName } from '@volter/world-core';
+import { stateDirName } from '@volter/world-core/runtime';
 import { loadWorldConfig } from '@volter/world-runtime';
 export const WORLD_FILE = 'world.json';
 /** `<root>/.volter` */

package/dist/src/mcp.js

@@ -78,7 +78,7 @@ Work in the app's folder (each tool takes "dir", defaulting to where this server
 - Look: world_log and world_diff say what the app changed at each vendor; world_view starts the dashboard and returns its link for the person.
 - Branch and reset like a database: world_branch, world_checkout, world_reset.
 - Share with a team: platform_login returns a link and a code the PERSON must approve in their browser (you cannot approve it); after they do, remote_link links this World to <org>/<world> on the platform (create: true makes it there from this World's vendors); world_changeset cuts the changes with a message, and world_push sends them.
-The guide: https://github.com/volter-ai/twin/blob/main/docs/guides/use-with-a-coding-agent.md`;
+The guide: https://github.com/volter-ai/twin-world/blob/main/docs/guides/use-with-a-coding-agent.md`;
 export async function serveMcp(version) {
     const server = new McpServer({ name: 'volter', title: 'Volter World', version }, { instructions: INSTRUCTIONS });
     const here = (dir) => resolve(dir ?? process.cwd());

package/dist/src/world.d.ts

@@ -1,6 +1,6 @@
-import { rebaseChangeset, worldBootMarker, type Changeset, type LedgerDelta, type TwinAction, type WorldMarker, type ApplyReceipt, applyTwinWrite, type TwinResource } from '@volter/world-core';
+import { rebaseChangeset, worldBootMarker, type Changeset, type LedgerDelta, type TwinAction, type WorldMarker, type ApplyReceipt, applyTwinWrite, type TwinResource } from '@volter/world-core/runtime';
 import { approveWorldChangeset, createWorldChangeset, downWorld, fetchFromOrigin, pushWorldChangeset, rebaseWorldChangeset, replayWorldChangeset, resetWorld, seedWorld, statusWorldChangeset, verifyWorldChangeset, type ServedWorld, type ViewConsole, type WorldView, rootCredentialInput, type DeployTwinOutcome, type ChangesetLocation, type InitOptions, type InitResult, type WorldInstance } from '@volter/world-runtime';
-import { rebaseBranch, type Receipt, type RootConfig } from '@volter/world-core';
+import { rebaseBranch, type Receipt, type RootConfig } from '@volter/world-core/runtime';
 export type WorldRef = {
     name?: string;
     root?: string;
@@ -53,7 +53,7 @@ export type WorldStatus = {
     };
     services: Record<string, {
         url?: string;
-        running: boolean; /** the pack's protocol major and its standing (protocol 1 is deprecated: served under a warning, its vendor half throws) */
+        running: boolean; /** the pack's protocol major and its standing (the kernel serves its own major and refuses any other) */
         protocol?: {
             major: number;
             standing: string;
@@ -201,7 +201,7 @@ export declare class World {
             console: string | null;
         }) => void;
     }): Promise<ServedWorld>;
-    /** `volter world view`: this World, its mirrors, its branches and the console on one origin (docs/contributing/architecture.md, "Viewing a World"). */
+    /** `volter world view`: this World, its twins' screens, its branches and the console on one origin (docs/contributing/architecture.md, "Viewing a World"). */
     view(opts?: {
         port?: number;
         host?: string;
@@ -224,6 +224,9 @@ export declare class World {
         url: string;
         namespace: string;
     } | null;
+    /** The origin the instance recorded, or null for a world that has never run (only world.json names it then);
+     *  any other failure to read the instance is said as it is. */
+    private recordedOrigin;
     /** The origin this world clones from and pushes to, or null: the default data is its only origin. */
     origin(): WorldInstance['origin'] | null;
     /**
@@ -245,7 +248,8 @@ export declare class World {
         fetched: Awaited<ReturnType<typeof fetchFromOrigin>>;
         rebased: ReturnType<World['rebaseBranch']>;
     }>;
-    /** Fetch what the origin observed since the last fetch. */
+    /** Fetch what the origin observed since the last fetch. A world that has never run (a teammate's checkout, linked
+     *  with `remote add`) is booted as a clone boots it, with no story, and brings the origin's whole log in. */
     fetch(opts?: {
         token?: string;
         services?: string[];
@@ -284,6 +288,7 @@ export declare class World {
     twin(vendor: string): {
         vendor: string;
         url?: string;
+        ingest?: string;
         root: RootConfig | null;
         credential: {
             placedAt: string;
@@ -296,6 +301,7 @@ export declare class World {
     sealTwinCredential(vendor: string, input: string): Promise<{
         placedAt: string;
         fingerprint: string;
+        mintedSigningSecret?: string;
     }>;
     /** A root's credential when none is piped in: the signed-in vault, else the repo's `.env` (decision 0033). */
     rootCredentialInput(vendor: string): ReturnType<typeof rootCredentialInput>;

package/dist/src/world.js

@@ -3,15 +3,15 @@
 // way git finds its repository; every method is a name for a world-runtime verb, in the words a
 // user reads. The `volter` command is one client of this class and adds nothing.
 import { platformPerson } from "./credentials.js";
-import { rebaseChangeset, worldBootMarker, listActions, isTwinBookkeeping, pushablePendingActions, pendingActions, applyTwinWrite, twinResources } from '@volter/world-core';
+import { rebaseChangeset, worldBootMarker, listActions, isTwinBookkeeping, pushablePendingActions, pendingActions, applyTwinWrite, twinResources } from '@volter/world-core/runtime';
 import { spawnSync } from 'node:child_process';
 import clockForm from '@volter/world-core/world-clock';
-import { activateScript, approveWorldChangeset, branchWorld, clockFile, checkoutWorld, createWorldChangeset, diffWorld, downWorld, fetchFromOrigin, findWorldChangeset, initWorld, listWorldChangesets, listWorldMarks, listWorlds, markWorld, pushWorldChangeset, rebaseWorldChangeset, replayWorldChangeset, resetWorld, runWithWorldEnv, seedWorld, shellWorld, statusWorld, statusWorldChangeset, upWorld, verifyWorldChangeset, worldLedgers, worldOrigin, bindLegacyCredentials, deployWorld, loadWorldConfig, writeWorldConfig, readServeRecord, refreshTwin, serveWorld, serveWorldView, findInstalledPackage, rootForControlRoot, sealTwinCredential, sealedCredentialInfo, setTwinRoot, credentialPayloadFrom, rootCredentialInput, withoutVaultSignIn, materializeRoots, worldChangesetRules } from '@volter/world-runtime';
+import { activateScript, approveWorldChangeset, branchWorld, clockFile, checkoutWorld, createWorldChangeset, diffWorld, downWorld, fetchFromOrigin, findWorldChangeset, initWorld, listWorldChangesets, listWorldMarks, listWorlds, markWorld, pushWorldChangeset, rebaseWorldChangeset, replayWorldChangeset, resetWorld, runWithWorldEnv, seedWorld, shellWorld, statusWorld, statusWorldChangeset, upWorld, verifyWorldChangeset, worldLedgers, worldOrigin, bindLegacyCredentials, deployWorld, loadWorldConfig, writeWorldConfig, readServeRecord, refreshTwin, serveWorld, serveWorldView, findInstalledPackage, rootForControlRoot, sealTwinCredential, sealedCredentialInfo, setTwinRoot, credentialPayloadFrom, rootCredentialInput, withoutVaultSignIn, materializeRoots, instanceDir, worldChangesetRules } from '@volter/world-runtime';
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { requireToken, storeToken } from "./credentials.js";
 import { currentBranch, findWorldRoot, mainBranch, requireWorldRoot, setCurrentBranch, worldConfigRelative, worldEnvPath, worldSeedPath } from "./locate.js";
-import { destinationOf, parentEntries, rebaseBranch } from '@volter/world-core';
+import { destinationOf, parentEntries, rebaseBranch } from '@volter/world-core/runtime';
 /** One change as `log` shows it: the write, and the receipt the vendor answered with once pushed. */
 /** A twin's branch log as the world reads it: the twin's name, the state service it records under, its control root. */
 /** `30d`, `12h`, `5m`, `90s` in ms. */
@@ -170,7 +170,9 @@ export class World {
             branches: listWorlds(this.root).map((w) => w.name).sort(),
             running: instance?.running ?? false,
             served: (() => { const r = readServeRecord(this.root); return r ? { base: r.base, pid: r.pid, startedAt: r.startedAt } : null; })(),
-            origin: instance?.origin ? { url: instance.origin.url, namespace: instance.origin.namespace, ...(instance.origin.fetchedAt ? { fetchedAt: instance.origin.fetchedAt } : {}) } : null,
+            // the origin push and pull use: the remote world.json names, with when it was last fetched (a world that only
+            // pushed to it has not fetched, but it has an origin all the same)
+            origin: (() => { const o = this.origin(); return o ? { url: o.url, namespace: o.namespace, ...(o.fetchedAt ? { fetchedAt: o.fetchedAt } : {}) } : null; })(),
             unpushed: instance ? this.unpushed().length : 0,
             changesets: { total: changesets.length, pushed: changesets.filter((c) => c.changeset.applied?.outcome === 'applied').length },
             services,
@@ -367,7 +369,7 @@ export class World {
     // ── serving ─────────────────────────────────────────────────────────────────────────────
     /** Serve this world on a port under `/<org>/<world>/`; returns when listening. */
     serve(opts = {}) { return serveWorld(this.name, { root: this.root, ...opts }); }
-    /** `volter world view`: this World, its mirrors, its branches and the console on one origin (docs/contributing/architecture.md, "Viewing a World"). */
+    /** `volter world view`: this World, its twins' screens, its branches and the console on one origin (docs/contributing/architecture.md, "Viewing a World"). */
     view(opts = {}) { const person = platformPerson(); return serveWorldView(this.name, { root: this.root, ...(person ? { localPerson: person } : {}), ...opts }); }
     // ── remotes ─────────────────────────────────────────────────────────────────────────────
     /** The vendors this world has a twin of, as world.json names them (a twin service's package, else its id). */
@@ -402,12 +404,24 @@ export class World {
             return parseOriginUrl(target);
         if (name !== 'origin')
             return null;
-        const recorded = worldOrigin(this.name, this.root);
+        const recorded = this.recordedOrigin();
         return recorded ? { url: recorded.url, namespace: recorded.namespace } : null;
     }
+    /** The origin the instance recorded, or null for a world that has never run (only world.json names it then);
+     *  any other failure to read the instance is said as it is. */
+    recordedOrigin() {
+        try {
+            return worldOrigin(this.name, this.root);
+        }
+        catch (error) {
+            if (/World instance not found/.test(String(error.message)))
+                return null;
+            throw error;
+        }
+    }
     // ── the origin ──────────────────────────────────────────────────────────────────────────
     /** The origin this world clones from and pushes to, or null: the default data is its only origin. */
-    origin() { const r = this.remote('origin'); const recorded = worldOrigin(this.name, this.root); return r ? { ...(recorded ?? {}), url: r.url, namespace: r.namespace } : recorded; }
+    origin() { const r = this.remote('origin'); const recorded = this.recordedOrigin(); return r ? { ...(recorded ?? {}), url: r.url, namespace: r.namespace } : recorded; }
     /**
      * Clone a remote's canonical history into this world: record the origin, remember the token,
      * fetch everything. With the world's token (namespace or read), the history arrives through the
@@ -436,14 +450,26 @@ export class World {
         const fetched = await this.fetch(opts);
         return { fetched, rebased: this.repos().map((r) => ({ service: r.service, ...rebaseBranch(r.stateService, r.root, { origin: true }) })) };
     }
-    /** Fetch what the origin observed since the last fetch. */
-    fetch(opts = {}) {
+    /** Fetch what the origin observed since the last fetch. A world that has never run (a teammate's checkout, linked
+     *  with `remote add`) is booted as a clone boots it, with no story, and brings the origin's whole log in. */
+    async fetch(opts = {}) {
         const origin = this.origin();
         if (!origin)
             throw new Error(`World "${this.name}" has no origin — its only origin is the default data. \`volter world clone <url>\` connects a remote.`);
         if (opts.token !== undefined && opts.token !== '')
             storeToken(origin.url, opts.token); // the last token given for a remote is the one remembered
-        return fetchFromOrigin(this.name, { root: this.root, url: origin.url, namespace: origin.namespace, key: requireToken(origin.url, opts.token), ...(opts.services ? { services: opts.services } : {}) });
+        const key = requireToken(origin.url, opts.token);
+        const instance = this.instance();
+        // state with no record is not a fresh checkout: a clean boot would take its unpushed work with it
+        if (!instance && existsSync(instanceDir(this.root, this.name)))
+            throw new Error(`World "${this.name}" has state but no instance record (${instanceDir(this.root, this.name)}): \`volter world up\` resumes it, or \`volter world down --purge\` starts it over`);
+        // a record missing a configured twin (a boot that failed part-way) is booted again, resuming what it holds
+        const configured = loadWorldConfig(this.configRef(), this.root).config.services.filter((s) => s.type === 'twin' || s.type === undefined).map((s) => s.id);
+        if (!instance || configured.some((id) => !(id in instance.services)))
+            await this.up({ seed: false });
+        // never fetched and nothing of its own: the origin's whole log, as a clone brings it
+        const full = !instance?.origin?.fetchedAt && this.log().length === 0;
+        return fetchFromOrigin(this.name, { root: this.root, url: origin.url, namespace: origin.namespace, key, ...(full ? { full: true } : {}), ...(opts.services ? { services: opts.services } : {}) });
     }
     // ── changesets and push ─────────────────────────────────────────────────────────────────
     /** Cut a changeset from the unpushed changes: the reviewable unit, with the author's message. */
@@ -503,7 +529,9 @@ export class World {
         if (!service)
             throw new Error(`no twin "${vendor}" in this world`);
         const inst = this.instance();
-        return { vendor, ...(inst?.services[vendor]?.url ? { url: inst.services[vendor].url } : {}), root: service.root ?? null, credential: sealedCredentialInfo(this.root, vendor) };
+        // the door the vendor's webhooks are registered at: a served World's (architecture, "Ingest")
+        const served = readServeRecord(this.root);
+        return { vendor, ...(inst?.services[vendor]?.url ? { url: inst.services[vendor].url } : {}), ...(served ? { ingest: `${served.base.replace(/\/+$/, '')}/twins/${vendor}/ingest` } : {}), root: service.root ?? null, credential: sealedCredentialInfo(this.root, vendor) };
     }
     /** Set (or clear) the twin's root: the vendor's API and the deploy policy, in world.json. Takes effect at the next `up` or `serve`, or now when the world runs. */
     setTwinRoot(vendor, root) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world",
-  "version": "2.0.58",
+  "version": "3.0.1",
   "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",
@@ -15,7 +15,7 @@
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/volter-ai/twin.git",
+    "url": "git+https://github.com/volter-ai/twin-world.git",
     "directory": "packages/cli"
   },
   "publishConfig": {
@@ -30,12 +30,12 @@
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.1",
-    "@volter/world-core": "2.0.37",
-    "@volter/world-runtime": "2.0.55",
+    "@volter/world-core": "3.0.1",
+    "@volter/world-runtime": "3.0.1",
     "zod": "^4.6.5"
   },
   "peerDependencies": {
-    "@volter/world-console": "2.0.18"
+    "@volter/world-console": "3.0.1"
   },
   "peerDependenciesMeta": {
     "@volter/world-console": {
@@ -43,7 +43,7 @@
     }
   },
   "devDependencies": {
-    "@volter/world-console": "2.0.18"
+    "@volter/world-console": "3.0.1"
   },
   "bin": {
     "volter": "dist/src/cli.js"

package/skills/volter-world/AGENTS.md

@@ -7,13 +7,13 @@ environment injection, a Node preload and a scoped HTTPS proxy route configured
 The state model is **Neon for every SaaS**: a log, checkpoints and branches over a parent position.
 Git-inspired verbs describe operations; there is no staging or commit step. Push moves entries
 between Worlds. Deploy performs them against a vendor at a real-system root under its policy.
-The canonical [model](https://github.com/volter-ai/twin/blob/main/docs/concepts/the-model.md),
-[lifecycle](https://github.com/volter-ai/twin/blob/main/docs/concepts/worlds.md) and
-[CLI reference](https://github.com/volter-ai/twin/blob/main/docs/reference/cli.md) own the details.
+The canonical [model](https://github.com/volter-ai/twin-world/blob/main/docs/concepts/the-model.md),
+[lifecycle](https://github.com/volter-ai/twin-world/blob/main/docs/concepts/worlds.md) and
+[CLI reference](https://github.com/volter-ai/twin-world/blob/main/docs/reference/cli.md) own the details.
 
 ## Set up a World for an app
 
-In the app's folder (the [guide](https://github.com/volter-ai/twin/blob/main/docs/guides/use-with-a-coding-agent.md)):
+In the app's folder (the [guide](https://github.com/volter-ai/twin-world/blob/main/docs/guides/use-with-a-coding-agent.md)):
 
 ```bash
 npm install -g @volter/world     # once; `volter agents install` then adds this skill and the MCP server to your agents

package/skills/volter-world/SKILL.md

@@ -10,5 +10,5 @@ operator instruction source shipped with this skill: setting a World up for an a
 to a platform, the `volter mcp` tools, and the lifecycle distinction between the product command
 `volter world` and the explicit operator command `volter-world`.
 
-The [documentation map](https://github.com/volter-ai/twin/blob/main/docs/README.md) links the
+The [documentation map](https://github.com/volter-ai/twin-world/blob/main/docs/README.md) links the
 canonical model, task guides and command reference. Do not maintain a second copy here.

package/src/agents.ts

@@ -69,7 +69,7 @@ const writeJson = (path: string, value: unknown): void => writeAtomic(path, `${J
 /** A command run as itself; on Windows, where `claude` is a .cmd that runs only in cmd, one line to cmd with each argument
  *  quoted (a path with a space stays one argument), as cross-spawn does. */
 const runTool = (bin: string, args: string[]): ReturnType<typeof spawnSync> => process.platform === 'win32'
-  ? spawnSync(process.env.ComSpec ?? 'cmd.exe', ['/d', '/s', '/c', `"${[bin, ...args].map((a) => `"${a.replace(/"/g, '""')}"`).join(' ')}"`], { windowsHide: true, encoding: 'utf8', windowsVerbatimArguments: true })
+  ? spawnSync(process.env.ComSpec ?? 'cmd.exe', ['/d', '/s', '/c', `"${[bin, ...args].map((a) => `"${a.replaceAll('"', '""')}"`).join(' ')}"`], { windowsHide: true, encoding: 'utf8', windowsVerbatimArguments: true })
   : spawnSync(bin, args, { windowsHide: true, encoding: 'utf8' });
 const same = (a: unknown, b: unknown): boolean => JSON.stringify(a) === JSON.stringify(b);
 

package/src/cli.ts

@@ -9,7 +9,7 @@ import { fileURLToPath } from 'node:url';
 import { spawn, spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { hostname } from 'node:os';
-import { formatLedgerDelta } from '@volter/world-core';
+import { formatLedgerDelta } from '@volter/world-core/runtime';
 import { existsSync } from 'node:fs';
 import { join, relative, resolve } from 'node:path';
 import { forgetPlatform, forgetToken, platformOrigin, requireToken, storePlatform, storeToken, tokenFor } from './credentials.ts';
@@ -56,7 +56,7 @@ world  — the twins your app needs, running together (the world of the current
   volter world changeset [<name>] -m "<message>"         cut the unpushed changes into a reviewable changeset
   volter world pull [--token <token>]                    fetch, then move this branch onto what came in (git's pull)
   volter world push [<name>] [--token <token>] [--force] push to the remote, which deploys and answers with receipts
-  volter world rebase [<changeset>]                      rebase this branch onto its moved base, or a changeset onto the moved mirror
+  volter world rebase [<changeset>]                      rebase this branch onto its moved base, or a changeset onto the moved remote
   volter world verify <changeset>                        run the world's checks over a changeset and record the result
   volter world approve <changeset> --as <principal>      sign a changeset's current hash
   volter world deploy [<changeset>]                      perform landed changes against each twin's root, by its policy
@@ -67,8 +67,6 @@ twin   — one twin: in this world, or on its own
   volter twin <vendor> credential                        seal a credential read from stdin beside the world; never readable back
   volter twin <vendor> refresh                           observe the root now
   volter twin <vendor> serve [--port <p>] [--read-only]  serve the twin; your SDK talks to it at http://127.0.0.1:<p>
-  volter twin <vendor> mirror [--port <p>]               the twin's UI mirror
-  volter twin <vendor> conformance                       check the twin against the vendor's spec
 
 agents — your coding agent, driving the same verbs
   volter agents install [--claude] [--cursor] [--vscode] [--codex] [--yes]   put the volter-world skill and the MCP server into the agents found here
@@ -88,6 +86,7 @@ remote — the worlds this one pushes to and fetches from, by name
   --world <dir>    the world root, when the cwd is not inside it
   --branch <name>  act on that branch instead of the checked-out one
   --json           machine-readable output where offered
+  --version        the command's version
 `;
 
 function flag(args: string[], name: string): boolean { return args.includes(name); }
@@ -197,6 +196,10 @@ async function worldCommand(verb: string, args: string[]): Promise<void> {
     case 'run': {
       const command = afterDashes(args);
       if (command.length === 0) throw new Error('volter world run: give the command after --  (volter world run -- npm test)');
+      // a stopped World is started first, as `volter world up` does (the default data the first time), and left running
+      let running = false; try { running = world.instance()?.running ?? false; } catch { /* never started */ }
+      if (!running) { process.stderr.write(`${world.name} is not running: starting it (volter world up)
+`); await world.up({ seed: true }); }
       process.exitCode = await world.run(command, { verbose: flag(args.slice(0, args.indexOf('--')), '--verbose') });
       return;
     }
@@ -337,7 +340,7 @@ async function worldCommand(verb: string, args: string[]): Promise<void> {
         process.exit(0); // success follows confirmed shutdown; failures reach main's error path
         return;
       }
-      // the console mounts when it is installed beside the CLI; without it the World serves its doors and mirrors
+      // the console mounts when it is installed beside the CLI; without it the World serves its doors and the twins
       const console = await (async (): Promise<ViewConsole | undefined> => {
         try { const mod = await import('@volter/world-console') as { createConsole: () => ViewConsole }; return mod.createConsole(); } catch (error) {
           // not installed is one thing; installed and broken is another, and says why
@@ -423,7 +426,7 @@ async function worldCommand(verb: string, args: string[]): Promise<void> {
   }
 }
 
-/** `volter twin <vendor> <verb…>`: the twin's own CLI (serve, mirror, conformance), found the way a world finds it. */
+/** `volter twin <vendor> <verb…>`: the twin's own CLI (serve), found the way a world finds it. */
 async function twinCommand(args: string[]): Promise<void> {
   const [vendor, ...rest] = args;
   if (!vendor || vendor.startsWith('-')) throw new Error('volter twin: which twin? (volter twin stripe serve --port 12111)');
@@ -450,7 +453,9 @@ async function twinCommand(args: string[]): Promise<void> {
         out(`${vendor}  credential from ${found.from}`);
         input = found.input;
       }
-      await world.sealTwinCredential(vendor, input);
+      const sealed = await world.sealTwinCredential(vendor, input);
+      // the root runbook: the ingest door's secret, shown once
+      if (sealed.mintedSigningSecret) out(`${vendor}  signing secret ${sealed.mintedSigningSecret}  (enter it at the vendor as the webhook's secret; it is not shown again. A vendor that issues its own seals it instead: {"headers": {...}, "signingSecret": "<the vendor's>"})`);
     } else if (verb === 'refresh') {
       const r = await world.refreshTwin(vendor, { force: flag(rest, '--force') });
       out(r.refreshed ? `${vendor}  refreshed  ${r.report?.appended ?? 0} changed, ${r.report?.removed ?? 0} gone, ${r.report?.unchanged ?? 0} unchanged` : `${vendor}  not refreshed: ${r.reason}`);
@@ -459,11 +464,13 @@ async function twinCommand(args: string[]): Promise<void> {
     const t = world.twin(vendor);
     if (flag(rest, '--json')) { json(t); return; }
     out(`${vendor}  ${t.root ? `root ${t.root.url}${t.root.scope ? `/${t.root.scope}` : ''}  deploy ${t.root.deploy}` : 'no root'}  ${t.credential ? 'credential sealed' : 'no credential'}${t.url ? `  ${t.url}` : ''}`);
+    // the root runbook: where the vendor's webhooks go
+    if (t.root) out(t.ingest ? `${vendor}  ingest ${t.ingest}  (register it at the vendor as the webhook URL, with the signing secret sealed with the credential)` : `${vendor}  ingest: a served World's door (volter world serve, or a remote) is the webhook URL to register at the vendor`);
     return;
   }
   const dir = resolveCatalog(process.cwd()).packDir(vendor);
   if (dir === undefined) throw new Error(`No twin "${vendor}" here — \`bun add -d @volter/twin-${vendor}\`, or run from a checkout that has it`);
-  if (rest.length === 0 || rest[0]!.startsWith('-')) throw new Error(`volter twin ${vendor}: which verb? serve | mirror | conformance`);
+  if (rest.length === 0 || rest[0]!.startsWith('-')) throw new Error(`volter twin ${vendor}: which verb? serve | root | credential | refresh`);
   const cli = packCli(dir); if (cli === undefined) throw new Error(`No cli for twin "${vendor}" (its manifest names no bin)`);
   process.exitCode = await passthrough([process.execPath, cli, ...rest]);
 }
@@ -487,10 +494,15 @@ async function loginCommand(args: string[]): Promise<void> {
   let origin: string; try { const u = new URL(url); if (u.protocol !== 'https:' && u.protocol !== 'http:') throw new Error(); origin = u.origin; } catch { throw new Error(`${url} is not a platform address (https://…)`); }
   const token = value(args, '--token') ?? await deviceSignIn(origin, !flag(args, '--no-open'));
   const res = await fetch(`${origin}/-/orgs`, { headers: { authorization: `Bearer ${token}` } });
-  const body = (await res.json().catch(() => ({}))) as { person?: { email?: string; id?: string }; orgs?: Array<{ slug: string | null; name: string }>; error?: string };
+  const body = (await res.json().catch(() => ({}))) as { person?: { email?: string; id?: string }; orgs?: Array<{ slug: string | null; name: string; worlds?: Array<{ name: string }> }>; error?: string };
   if (!res.ok) throw new Error(`${origin} answered ${res.status}: ${body.error ?? 'not signed in'}`);
   storeToken(origin, token); storePlatform(origin, undefined, body.person?.email ?? body.person?.id);
-  out(`signed in  ${origin}  as ${body.person?.email ?? body.person?.id ?? 'you'}\norgs       ${(body.orgs ?? []).map((o) => o.slug ?? o.name).join(', ') || '(none yet)'}\nnext       in your app's folder: volter world init, then volter remote add origin ${(body.orgs ?? [])[0]?.slug ?? '<org>'}/<world> --create`);
+  // a teammate's orgs already hold Worlds: the next step links one; a first person's makes one
+  const held = (body.orgs ?? []).flatMap((o) => (o.worlds ?? []).map((w) => w.name));
+  const next = held.length
+    ? `in your app's folder: volter remote add origin ${held[0]}, then volter world pull${held.length > 1 ? `  (your orgs' Worlds: ${held.slice(0, 6).join(', ')}${held.length > 6 ? ', …' : ''})` : ''}`
+    : `in your app's folder: volter world init, then volter remote add origin ${(body.orgs ?? [])[0]?.slug ?? '<org>'}/<world> --create`;
+  out(`signed in  ${origin}  as ${body.person?.email ?? body.person?.id ?? 'you'}\norgs       ${(body.orgs ?? []).map((o) => o.slug ?? o.name).join(', ') || '(none yet)'}\nnext       ${next}`);
 }
 
 /** `volter whoami`: which platform the command is signed into, as whom, and the orgs it reaches. */
@@ -498,7 +510,7 @@ async function whoamiCommand(): Promise<void> {
   const origin = platformOrigin(); const token = origin ? tokenFor(origin) : undefined;
   if (!origin || !token) { out('not signed in  (volter login <platform url>)'); process.exitCode = 1; return; }
   const res = await fetch(`${origin}/-/orgs`, { headers: { authorization: `Bearer ${token}` } }).catch(() => null);
-  if (!res) throw new Error(`${origin} did not answer`);
+  if (!res) throw new Error(`${origin} did not answer: the platform this command is signed into is unreachable (volter login <url> signs it into another)`);
   const body = (await res.json().catch(() => ({}))) as { person?: { email?: string; id?: string }; orgs?: Array<{ slug: string | null; name: string; role?: string }>; error?: string };
   // a token the platform no longer takes is signed out; one it takes but that may not read orgs is still signed in
   if (res.status === 403) { out(`signed in  ${origin}  (this token may not read your orgs: ${body.error ?? 'refused'})`); return; }
@@ -749,6 +761,7 @@ async function main(): Promise<void> {
 async function dispatch(noun: string | undefined, verb: string | undefined, args: string[]): Promise<void> {
   if (!noun || noun === '--help' || noun === '-h' || noun === 'help') { out(HELP); return; }
   if (verb === '--help' || verb === '-h') { out(HELP); return; }
+  if (noun === '--version' || noun === '-v' || noun === 'version') { out(`volter ${ownVersion()}`); return; }
   switch (noun) {
     case 'world': {
       if (!verb) throw new Error(`volter world: which verb?\n\n${HELP}`);

package/src/handlers-in-repo.test.ts

@@ -2,14 +2,15 @@
 // #the-config-and-the-running-world): init copies a twin's starter handlers to .volter/handlers/<vendor>.json and
 // names that path relative to the world root, so the committed config reads the same on every
 // machine; `up` resolves it against the root on both the spawn path (--scenario) and the colocated
-// host (scenarioPath). Proven against the real anthropic twin, which ships starter handlers.
+// host (scenarioPath). Proven against the real anthropic twin, installed with starter handlers of the test's own (no
+// pack of the catalog ships any): its files linked from the pack repository, its `defaults/handlers.json` written here.
 import { afterAll, describe, expect, test } from 'bun:test';
-import { mkdirSync, mkdtempSync, readFileSync, symlinkSync, writeFileSync } from 'node:fs';
+import { copyFileSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, symlinkSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { World } from './index.ts';
 
-const PACKS = resolve(import.meta.dir, '..', '..', 'twin');
+const PACKS = resolve(import.meta.dir, '..', '..', '..', '..', 'twin-packs-p3');
 
 function app(): string {
   const parent = mkdtempSync(join(tmpdir(), 'handlers-in-repo-'));
@@ -17,8 +18,14 @@ function app(): string {
   mkdirSync(dir);
   writeFileSync(join(dir, 'package.json'), JSON.stringify({ name: 'agent', dependencies: { '@anthropic-ai/sdk': '^0.30' } }));
   writeFileSync(join(dir, '.env.example'), 'ANTHROPIC_API_KEY=\n');
-  mkdirSync(join(parent, 'node_modules', '@volter'), { recursive: true });
-  symlinkSync(join(PACKS, 'anthropic'), join(parent, 'node_modules', '@volter', 'twin-anthropic'));
+  const installed = join(parent, 'node_modules', '@volter', 'twin-anthropic');
+  mkdirSync(installed, { recursive: true });
+  for (const entry of readdirSync(join(PACKS, 'anthropic'))) {
+    if (entry === 'package.json') copyFileSync(join(PACKS, 'anthropic', entry), join(installed, entry));
+    else symlinkSync(join(PACKS, 'anthropic', entry), join(installed, entry));
+  }
+  mkdirSync(join(installed, 'defaults'));
+  writeFileSync(join(installed, 'defaults', 'handlers.json'), `${JSON.stringify({ handlers: [{ id: 'demo-answer', on: {}, respond: { text: 'hi' } }] }, null, 2)}\n`);
   return dir;
 }
 

package/src/journeys/kit.ts

@@ -6,7 +6,7 @@ import { resolve } from 'node:path';
 export const CLI = resolve(import.meta.dir, '..', 'cli.ts');
 /** The operator's `volter-world` command, which ships with @volter/world-runtime. */
 export const OPERATOR_CLI = resolve(import.meta.dir, '..', '..', '..', 'world-runtime', 'src', 'cli.ts');
-/** The twins, as this checkout holds them. */
-export const PACKS = resolve(import.meta.dir, '..', '..', '..', 'twin');
+/** The twins: the pack repository beside this checkout. */
+export const PACKS = resolve(import.meta.dir, '..', '..', '..', '..', '..', 'twin-packs-p3');
 /** @volter/world itself. */
 export const SDK = resolve(import.meta.dir, '..', '..');

package/src/journeys/tutorial.ts

@@ -17,7 +17,7 @@
 //
 // The same steps make the recording: `tapeFor(page)` renders a vhs tape that types each command,
 // waits, and screenshots after each one, so docs/media/<page>/ is the page's own playback.
-import { existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
 import { downWorld } from '@volter/world-runtime';
 import { tmpdir } from 'node:os';
 import { basename, delimiter, dirname, join, resolve } from 'node:path';
@@ -108,7 +108,9 @@ const globalPath = (global: string): string => [...(process.platform === 'win32'
  * package.json, its env example, its files — and installs what it names.
  */
 export function tutorialApp(name: string, registry: { env: Record<string, string> }): { dir: string; parent: string; env: Record<string, string> } {
-  const parent = mkdtempSync(join(tmpdir(), `tutorial-${name}-`));
+  // the real path: macOS's temp directory is a symlink (/var → /private/var), and a World is known by its root's real
+  // path, so the harness and the CLI the page runs name it alike
+  const parent = realpathSync(mkdtempSync(join(tmpdir(), `tutorial-${name}-`)));
   const dir = join(parent, 'acme-web');
   mkdirSync(dir);
   const global = join(parent, 'bun-global');
@@ -227,6 +229,7 @@ export async function runTutorial(tutorial: Tutorial, app: { dir: string; parent
   };
   const fenceOutput = new Map<number, string>(); // what the reader saw after each bash fence, all its commands
   const backgroundFences = new Set<number>();
+  let leak: Error | undefined;
   try {
     for (const step of tutorial.steps) {
       if (step.kind === 'file') {
@@ -282,9 +285,13 @@ export async function runTutorial(tutorial: Tutorial, app: { dir: string; parent
       const alive = new Set(windowsProcesses().map((p) => `${p.pid}@${p.created}`));
       for (const p of leftovers) if (alive.has(`${p.pid}@${p.created}`)) Bun.spawnSync({ cmd: ['taskkill', '/PID', String(p.pid), '/T', '/F'], windowsHide: true, stdout: 'ignore', stderr: 'ignore' });
       await Promise.allSettled([reader.cancel(), errReader.cancel()]);
-      throw new Error(`the page left ${leftovers.length} process(es) running after its own stop and the harness's kill of its jobs (ended now):\n${leftovers.map((p) => `  pid ${p.pid}: ${p.command}`).join('\n')}`);
+      // not thrown here: a throw in `finally` replaces the page's own failure with this report. It is thrown after,
+      // when the page itself passed; when the page failed, its failure propagates and this is printed beside it
+      leak = new Error(`the page left ${leftovers.length} process(es) running after its own stop and the harness's kill of its jobs (ended now):\n${leftovers.map((p) => `  pid ${p.pid}: ${p.command}`).join('\n')}`);
+      console.error(leak.message);
     }
   }
+  if (leak) throw leak;
   return results;
 }
 

package/src/locate.ts

@@ -4,7 +4,7 @@
 // `World.open()` start here, the way `git` starts from the nearest `.git`.
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
-import { stateDirName } from '@volter/world-core';
+import { stateDirName } from '@volter/world-core/runtime';
 import { loadWorldConfig } from '@volter/world-runtime';
 
 export const WORLD_FILE = 'world.json';

package/src/mcp.ts

@@ -72,7 +72,7 @@ Work in the app's folder (each tool takes "dir", defaulting to where this server
 - Look: world_log and world_diff say what the app changed at each vendor; world_view starts the dashboard and returns its link for the person.
 - Branch and reset like a database: world_branch, world_checkout, world_reset.
 - Share with a team: platform_login returns a link and a code the PERSON must approve in their browser (you cannot approve it); after they do, remote_link links this World to <org>/<world> on the platform (create: true makes it there from this World's vendors); world_changeset cuts the changes with a message, and world_push sends them.
-The guide: https://github.com/volter-ai/twin/blob/main/docs/guides/use-with-a-coding-agent.md`;
+The guide: https://github.com/volter-ai/twin-world/blob/main/docs/guides/use-with-a-coding-agent.md`;
 
 export async function serveMcp(version: string): Promise<void> {
   const server = new McpServer({ name: 'volter', title: 'Volter World', version }, { instructions: INSTRUCTIONS });

package/src/sdk.test.ts

@@ -53,7 +53,7 @@ describe('World — the twins an app needs, running together', () => {
     // the default data is the only origin: nothing to push to, nothing to fetch from
     expect(world.origin()).toBeNull();
     await expect(world.push()).rejects.toThrow(/default data cannot be pushed to/);
-    expect(() => world.fetch()).toThrow(/only origin is the default data/);
+    await expect(world.fetch()).rejects.toThrow(/only origin is the default data/);
 
     // a branch over the same mirrors with its own log, checked out; checkout switches back
     const feature = await world.branch('feature');
@@ -74,7 +74,7 @@ describe('World — the twins an app needs, running together', () => {
     expect(back.status().running).toBe(true);
     expect(back.unpushed()).toHaveLength(1);
     await back.down();
-  });
+  }, 30_000); // two Worlds booted and one resumed: its one-service skeleton alone took 2.4 s (load ~13, 2026-09-30, a scratch probe of up/branch/checkout/down/up/down)
 
   test('a remote URL names one world; tokens live in the user\'s config dir, never in the repo', () => {
     expect(parseOriginUrl('https://twins.example.com/acme/web')).toEqual({ url: 'https://twins.example.com', namespace: 'acme/web' });

package/src/world.ts

@@ -3,7 +3,7 @@
 // way git finds its repository; every method is a name for a world-runtime verb, in the words a
 // user reads. The `volter` command is one client of this class and adds nothing.
 import { platformPerson } from './credentials.ts';
-import { rebaseChangeset, worldBootMarker, type Changeset, type ChangesetApplication, type LedgerDelta, type PerformAction, type RemoteExecute, type TwinAction, type WorldMarker, type ApplyReceipt, listActions, isTwinBookkeeping, pushablePendingActions, pendingActions, applyTwinWrite, twinResources, type TwinResource } from '@volter/world-core';
+import { rebaseChangeset, worldBootMarker, type Changeset, type ChangesetApplication, type LedgerDelta, type PerformAction, type RemoteExecute, type TwinAction, type WorldMarker, type ApplyReceipt, listActions, isTwinBookkeeping, pushablePendingActions, pendingActions, applyTwinWrite, twinResources, type TwinResource } from '@volter/world-core/runtime';
 import { spawnSync } from 'node:child_process';
 import clockForm from '@volter/world-core/world-clock';
 import {
@@ -11,12 +11,12 @@ import {
   statusWorld, statusWorldChangeset, upWorld, verifyWorldChangeset, worldLedgers, worldOrigin,
   bindLegacyCredentials, deployWorld, loadWorldConfig, writeWorldConfig, readServeRecord, refreshTwin, serveWorld, serveWorldView, findInstalledPackage, type ServedWorld, type ViewConsole, type WorldView, rootForControlRoot, sealTwinCredential, sealedCredentialInfo, setTwinRoot, credentialPayloadFrom, rootCredentialInput, withoutVaultSignIn,
   type DeployTwinOutcome, type MaterializedRoot,
-  type ChangesetLocation, type InitOptions, type InitResult, type WorldInstance, materializeRoots, worldChangesetRules } from '@volter/world-runtime';
+  type ChangesetLocation, type InitOptions, type InitResult, type WorldInstance, materializeRoots, instanceDir, worldChangesetRules } from '@volter/world-runtime';
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { requireToken, storeToken } from './credentials.ts';
 import { currentBranch, findWorldRoot, mainBranch, requireWorldRoot, setCurrentBranch, worldConfigRelative, worldEnvPath, worldSeedPath } from './locate.ts';
-import { destinationOf, parentEntries, rebaseBranch, type Receipt, type RootConfig } from '@volter/world-core';
+import { destinationOf, parentEntries, rebaseBranch, type Receipt, type RootConfig } from '@volter/world-core/runtime';
 
 export type WorldRef = { name?: string; root?: string };
 export type WorldMode = 'local' | 'share' | 'sealed';
@@ -56,7 +56,7 @@ export type WorldStatus = {
   origin: { url: string; namespace: string; fetchedAt?: string } | null;
   unpushed: number;
   changesets: { total: number; pushed: number };
-  services: Record<string, { url?: string; running: boolean; /** the pack's protocol major and its standing (protocol 1 is deprecated: served under a warning, its vendor half throws) */ protocol?: { major: number; standing: string } }>;
+  services: Record<string, { url?: string; running: boolean; /** the pack's protocol major and its standing (the kernel serves its own major and refuses any other) */ protocol?: { major: number; standing: string } }>;
   envFile?: string;
 };
 
@@ -175,7 +175,9 @@ export class World {
       branches: listWorlds(this.root).map((w) => w.name).sort(),
       running: instance?.running ?? false,
       served: (() => { const r = readServeRecord(this.root); return r ? { base: r.base, pid: r.pid, startedAt: r.startedAt } : null; })(),
-      origin: instance?.origin ? { url: instance.origin.url, namespace: instance.origin.namespace, ...(instance.origin.fetchedAt ? { fetchedAt: instance.origin.fetchedAt } : {}) } : null,
+      // the origin push and pull use: the remote world.json names, with when it was last fetched (a world that only
+      // pushed to it has not fetched, but it has an origin all the same)
+      origin: (() => { const o = this.origin(); return o ? { url: o.url, namespace: o.namespace, ...(o.fetchedAt ? { fetchedAt: o.fetchedAt } : {}) } : null; })(),
       unpushed: instance ? this.unpushed().length : 0,
       changesets: { total: changesets.length, pushed: changesets.filter((c) => c.changeset.applied?.outcome === 'applied').length },
       services,
@@ -338,7 +340,7 @@ export class World {
   // ── serving ─────────────────────────────────────────────────────────────────────────────
   /** Serve this world on a port under `/<org>/<world>/`; returns when listening. */
   serve(opts: { port?: number; host?: string; consolePort?: number; announce?: (info: { name: string; base: string; token: string; readToken: string; console: string | null }) => void } = {}): Promise<ServedWorld> { return serveWorld(this.name, { root: this.root, ...opts }); }
-  /** `volter world view`: this World, its mirrors, its branches and the console on one origin (docs/contributing/architecture.md, "Viewing a World"). */
+  /** `volter world view`: this World, its twins' screens, its branches and the console on one origin (docs/contributing/architecture.md, "Viewing a World"). */
   view(opts: { port?: number; host?: string; console?: ViewConsole; announce?: (line: string) => void; origins?: boolean; origin?: string } = {}): Promise<WorldView> { const person = platformPerson(); return serveWorldView(this.name, { root: this.root, ...(person ? { localPerson: person } : {}), ...opts }); }
 
   // ── remotes ─────────────────────────────────────────────────────────────────────────────
@@ -369,13 +371,18 @@ export class World {
     const target = this.remotes()[name];
     if (target) return parseOriginUrl(target);
     if (name !== 'origin') return null;
-    const recorded = worldOrigin(this.name, this.root);
+    const recorded = this.recordedOrigin();
     return recorded ? { url: recorded.url, namespace: recorded.namespace } : null;
   }
 
+  /** The origin the instance recorded, or null for a world that has never run (only world.json names it then);
+   *  any other failure to read the instance is said as it is. */
+  private recordedOrigin(): WorldInstance['origin'] | null {
+    try { return worldOrigin(this.name, this.root); } catch (error) { if (/World instance not found/.test(String((error as Error).message))) return null; throw error; }
+  }
   // ── the origin ──────────────────────────────────────────────────────────────────────────
   /** The origin this world clones from and pushes to, or null: the default data is its only origin. */
-  origin(): WorldInstance['origin'] | null { const r = this.remote('origin'); const recorded = worldOrigin(this.name, this.root); return r ? { ...(recorded ?? {}), url: r.url, namespace: r.namespace } : recorded; }
+  origin(): WorldInstance['origin'] | null { const r = this.remote('origin'); const recorded = this.recordedOrigin(); return r ? { ...(recorded ?? {}), url: r.url, namespace: r.namespace } : recorded; }
   /**
    * Clone a remote's canonical history into this world: record the origin, remember the token,
    * fetch everything. With the world's token (namespace or read), the history arrives through the
@@ -401,12 +408,22 @@ export class World {
     const fetched = await this.fetch(opts);
     return { fetched, rebased: this.repos().map((r) => ({ service: r.service, ...rebaseBranch(r.stateService, r.root, { origin: true }) })) };
   }
-  /** Fetch what the origin observed since the last fetch. */
-  fetch(opts: { token?: string; services?: string[] } = {}): ReturnType<typeof fetchFromOrigin> {
+  /** Fetch what the origin observed since the last fetch. A world that has never run (a teammate's checkout, linked
+   *  with `remote add`) is booted as a clone boots it, with no story, and brings the origin's whole log in. */
+  async fetch(opts: { token?: string; services?: string[] } = {}): ReturnType<typeof fetchFromOrigin> {
     const origin = this.origin();
     if (!origin) throw new Error(`World "${this.name}" has no origin — its only origin is the default data. \`volter world clone <url>\` connects a remote.`);
     if (opts.token !== undefined && opts.token !== '') storeToken(origin.url, opts.token); // the last token given for a remote is the one remembered
-    return fetchFromOrigin(this.name, { root: this.root, url: origin.url, namespace: origin.namespace, key: requireToken(origin.url, opts.token), ...(opts.services ? { services: opts.services } : {}) });
+    const key = requireToken(origin.url, opts.token);
+    const instance = this.instance();
+    // state with no record is not a fresh checkout: a clean boot would take its unpushed work with it
+    if (!instance && existsSync(instanceDir(this.root, this.name))) throw new Error(`World "${this.name}" has state but no instance record (${instanceDir(this.root, this.name)}): \`volter world up\` resumes it, or \`volter world down --purge\` starts it over`);
+    // a record missing a configured twin (a boot that failed part-way) is booted again, resuming what it holds
+    const configured = loadWorldConfig(this.configRef(), this.root).config.services.filter((s) => s.type === 'twin' || s.type === undefined).map((s) => s.id);
+    if (!instance || configured.some((id) => !(id in instance.services))) await this.up({ seed: false });
+    // never fetched and nothing of its own: the origin's whole log, as a clone brings it
+    const full = !instance?.origin?.fetchedAt && this.log().length === 0;
+    return fetchFromOrigin(this.name, { root: this.root, url: origin.url, namespace: origin.namespace, key, ...(full ? { full: true } : {}), ...(opts.services ? { services: opts.services } : {}) });
   }
 
   // ── changesets and push ─────────────────────────────────────────────────────────────────
@@ -456,12 +473,14 @@ export class World {
   rebase(name: string): ReturnType<typeof rebaseWorldChangeset> { return rebaseWorldChangeset(name, { root: this.root, world: this.name }); }
   // ── roots (docs/concepts/the-model.md: a twin on a shared world whose root is the vendor) ──
   /** The twin's root and credential, as `volter twin <vendor>` prints them. */
-  twin(vendor: string): { vendor: string; url?: string; root: RootConfig | null; credential: { placedAt: string; fingerprint: string } | null } {
+  twin(vendor: string): { vendor: string; url?: string; ingest?: string; root: RootConfig | null; credential: { placedAt: string; fingerprint: string } | null } {
     const { config } = loadWorldConfig(this.configRef(), this.root);
     const service = config.services.find((s) => s.id === vendor);
     if (!service) throw new Error(`no twin "${vendor}" in this world`);
     const inst = this.instance();
-    return { vendor, ...(inst?.services[vendor]?.url ? { url: inst.services[vendor]!.url } : {}), root: (service as { root?: RootConfig }).root ?? null, credential: sealedCredentialInfo(this.root, vendor) };
+    // the door the vendor's webhooks are registered at: a served World's (architecture, "Ingest")
+    const served = readServeRecord(this.root);
+    return { vendor, ...(inst?.services[vendor]?.url ? { url: inst.services[vendor]!.url } : {}), ...(served ? { ingest: `${served.base.replace(/\/+$/, '')}/twins/${vendor}/ingest` } : {}), root: (service as { root?: RootConfig }).root ?? null, credential: sealedCredentialInfo(this.root, vendor) };
   }
   /** Set (or clear) the twin's root: the vendor's API and the deploy policy, in world.json. Takes effect at the next `up` or `serve`, or now when the world runs. */
   setTwinRoot(vendor: string, root: RootConfig | null): void {
@@ -470,7 +489,7 @@ export class World {
     if (inst?.running) { materializeRoots(loadWorldConfig(this.configRef(), this.root).config, inst.dirs.data, this.root); }
   }
   /** Seal the vendor's credential beside the world (a bare token, or a JSON payload). Never readable back. */
-  sealTwinCredential(vendor: string, input: string): Promise<{ placedAt: string; fingerprint: string }> {
+  sealTwinCredential(vendor: string, input: string): Promise<{ placedAt: string; fingerprint: string; mintedSigningSecret?: string }> {
     // sealed for the one destination it serves, the twin's root: with none set there is nowhere it may go
     const url = (loadWorldConfig(this.configRef(), this.root).config.services as Array<{ id?: string; root?: { url?: string } }>).find((s) => s.id === vendor)?.root?.url;
     if (!url) return Promise.reject(new Error(`the ${vendor} twin has no root: \`volter twin ${vendor} root <url>\` sets where its credential goes, then seal it`));