joinweave 0.1.1 → 0.1.2

package/README.md

@@ -3,70 +3,125 @@
 The web wasn't built for agents. Weave was.
 
 ```sh
-npx joinweave@0.1.0
+npx joinweave@0.1.2
 ```
 
-Installs the prebuilt `weave` executable, creates `~/.weave` and `~/Weave`,
-initializes a local identity, runs a user-level background node, and checks live
-connectivity with `weave doctor`. No Rust toolchain or compilation is required.
-macOS and Linux arm64/x64 are supported; Windows is not supported in 0.1.0.
-Private keys stay in your local workspace.
+One command installs the developer runtime: the prebuilt native CLI, a local
+identity, a peer node, your workspace, and a persistent agent MCP server.
+A perspective woven ASCII scene follows the real installation stages. There
+are no simulated progress percentages, success messages or artificial delays.
+No Rust toolchain is required.
 
-The installer asks before adding a shell PATH line or editing any agent client
-configuration. Existing unrelated entries are retained. Conflicting files,
-modified installer entries and symbolic links are refused. Config edits use
-atomic replacements and private backup files beside the config.
+| Component | Installed location / behavior |
+| --- | --- |
+| Native CLI 0.1.0 | `~/.weave/bin/weave` |
+| Local identity and data | `~/.weave`; private keys stay on this computer |
+| Peer node | User-level launchd or systemd service |
+| Visible workspace | `~/Weave` |
+| MCP server 0.1.0 | `~/.weave/tools/mcp-0.1.0`; independent of the npx cache |
 
-For agents and unattended installs:
+Requirements: Node.js 20 or later with npm; macOS arm64/x64 (binary minimum
+load target macOS 11), or Linux arm64/x64 with glibc 2.39 or later. Linux arm64
+also needs the system OpenSSL 3 libraries (`libssl.so.3`, `libcrypto.so.3`).
+Linux managed services require a logged-in `systemd --user` session. Windows,
+musl and older glibc systems are unsupported. Native optional dependencies must
+be enabled when fetching joinweave's CLI dependency.
+
+The installer checks live connectivity with native `weave doctor`. A failed
+check remains an install failure. Your node and recoverable installation receipt
+remain available for a rerun. Doctor is a local runtime/connectivity check;
+independent discovery and sparse replication still require another live peer.
+
+The installer does not register an OpenAgentID or Life ID account and does not
+install a desktop application. Its component inventory describes only the
+runtime components actually installed by this release. The public distribution
+repository contains JavaScript tooling and prebuilt executables; Rust source is
+maintained separately in a private repository.
+
+## Consent and unattended use
+
+The MCP server is installed by default, but connecting an agent client requires
+separate consent. The installer asks before adding a shell PATH line or editing
+client settings. Existing unrelated entries are retained; conflicting files,
+modified installer entries and unsafe symbolic links are refused. Configuration
+edits use atomic replacements and private backup files beside the config.
+
+```sh
+npx joinweave@0.1.2 --yes --json
+```
+
+`--json` produces exactly one JSON result on stdout, with no animation, prompts
+or progress noise. Errors return `ok: false` and a nonzero exit status.
+`--yes` skips all PATH and client configuration questions. To explicitly consent:
 
 ```sh
-npx joinweave@0.1.0 --yes --json
+npx joinweave@0.1.2 --yes --path --mcp-client cursor,codex --json
 ```
 
-`--json` prints exactly one JSON result to stdout. Errors return `ok: false` and
-a nonzero exit status. A doctor failure is an install failure; a build or healthy
-process alone cannot substitute for peer discovery and an announce/find round
-trip. The node and recoverable installation receipt remain available for a rerun.
+The installer supports `claude-desktop`, `claude-code`, `cursor`, and `codex`.
+`one` and `bridge` provide a manual MCP definition; their settings are not
+written because no verified writable schema is available. Restart configured
+clients after installation. Start a new shell after adding PATH, or use the
+absolute binary path printed in the result.
 
-Options:
+Selected clients run the persistent MCP entry with the absolute Node executable
+used during installation and explicit `WEAVE_HOME` / `WEAVE_BINARY` values.
+They do not download MCP on startup. An existing owned npx-based configuration
+is migrated only when that client is explicitly selected again. Otherwise a
+headless rerun leaves client settings byte-for-byte unchanged. Keep that Node
+installation available for clients using it. If Node/nvm changes its location,
+a rerun with explicit `--mcp-client` consent migrates an intact owned entry to
+the current Node; a headless rerun leaves it unchanged. Uninstall still recognizes
+the exact owned old entry even if its Node executable is gone.
 
-- `--yes`: headless installation; skips PATH and MCP questions.
-- `--path`: explicitly consent to adding the managed shell PATH entry.
-- `--mcp-client cursor`: explicitly consent to configuring a named MCP client;
-  repeat or use a comma-separated list. Clients are `claude-desktop`,
-  `claude-code`, `cursor`, and `codex`. `one` and `bridge` print a manual setup
-  definition; their configuration files are not edited because no verified
-  writable MCP schema is available. These clients are detected when their
-  `.one`/`.bridge` directories or macOS application bundles are present.
-- `--no-mcp`: skip agent configuration.
-- `--no-service`: run a detached node with `weave node start` instead of
-  installing launchd or systemd. A live node is still required for doctor.
-- `--json`: machine-readable output, with no prompts.
+The MCP installation uses npm with `--ignore-scripts`, a private exclusive
+staging directory, the pinned published package integrity, and an owned
+file/mode census. User npm release-age policy is preserved. If a policy or a
+network failure prevents installation, fix that condition and rerun; no partial
+MCP tree is reported as installed.
 
-For example, consent to Cursor and Codex configuration headlessly:
+## Options and next actions
+
+- `--no-animation`: static progress; no cursor control or motion.
+- `NO_COLOR`: disable terminal colors. `TERM=dumb` and redirected output use
+  static progress automatically.
+- `--no-mcp`: skip MCP installation and client setup.
+- `--no-service`: start a detached node instead of an OS-managed service.
+- `--path`: consent to the managed shell PATH entry.
+- `--mcp-client CLIENT`: consent to a named client; repeat or separate names
+  with commas.
+- `--json`: machine-readable output without prompts.
+- `--yes`: headless installation; no implicit client or PATH consent.
 
 ```sh
-npx joinweave@0.1.0 --yes --path --mcp-client cursor,codex --json
+~/.weave/bin/weave node status --json
+~/.weave/bin/weave strand create --json
+~/.weave/bin/weave node logs
 ```
 
-The MCP configuration starts `npx --yes @useweave/mcp@0.1.0` with the persistent
-binary and workspace paths. The installed binary remains at `~/.weave/bin/weave`
-after npm's execution cache is cleaned. Restart configured agent clients after
-installation. Start a fresh shell after adding PATH, or use the absolute binary
-path printed in the JSON result.
+Use `weave node start`, `weave node stop`, `weave node status`, and
+`weave node logs` to manage the installed node. `WEAVE_HOME` can select a
+dedicated absolute workspace. See the [quickstart](https://docs.weave.earth/getting-started/quickstart)
+and [MCP reference](https://docs.weave.earth/tooling/mcp) for the supported runtime
+commands and ten MCP tools. Other library models are not added to the MCP tool
+surface by this installer.
 
-Manage the node with `weave node start`, `weave node stop`, `weave node status`,
-and `weave node logs`. Linux service installation requires an available
-`systemd --user` session. On a box without one, use `--no-service`.
-`WEAVE_HOME` can select a dedicated absolute workspace directory.
+## Recovery and removal
 
 ```sh
-npx joinweave@0.1.0 uninstall --yes
-npx joinweave@0.1.0 uninstall --yes --purge
+npx joinweave@0.1.2 uninstall --yes
+npx joinweave@0.1.2 uninstall --yes --purge
 ```
 
-Uninstall stops the node and removes only owned service, executable, PATH and
-MCP entries. It retains workspace data by default. `--purge` also deletes the
-dedicated workspace, including local identity keys; `~/Weave` is always
-preserved because it may contain unrelated user files. Modified installer
-entries are retained and reported instead of being overwritten or deleted.
+Uninstall stops the node and removes only owned service, executable, PATH,
+client entries and the unchanged managed MCP tree. It retains identity and
+workspace data by default. `--purge` also deletes the dedicated workspace,
+including private identity keys. `~/Weave` is always preserved because it may
+contain unrelated files. Modified entries are preserved and reported; they
+block purge. An interruption preserves recoverable installed components; rerun
+the installer to continue.
+
+Cancellation waits for the installer child process to close, with bounded
+SIGTERM/SIGKILL escalation. If termination cannot be confirmed, its persistent
+lock and MCP stage are retained. A new installer refuses the lock while its
+recorded parent or child is alive; do not manually remove it under a live process.

package/bin/joinweave.js

@@ -1,38 +1,65 @@
 #!/usr/bin/env node
 import { createInterface } from 'node:readline/promises';
-import { Installer, VERSION, parseArgs } from '../src/installer.js';
+import { Installer, InstallError, VERSION, parseArgs } from '../src/installer.js';
+import { TerminalPresenter, installationSummary } from '../src/terminal.js';
 
 const jsonRequested = process.argv.slice(2).includes('--json');
-let prompt;
+const controller = new AbortController();
+let prompt, presenter, interrupted;
+const interrupt = (signal) => {
+  interrupted ||= signal;
+  presenter?.finish();
+  controller.abort();
+};
+const onInt = () => interrupt('SIGINT'), onTerm = () => interrupt('SIGTERM');
 try {
   const options = parseArgs(process.argv.slice(2));
   if (options.help) {
-    const usage = 'joinweave [uninstall] [--yes] [--json] [--no-service] [--no-mcp] [--path] [--mcp-client CLIENT] [--purge]\n\n--yes installs headlessly; PATH and MCP edits require --path and --mcp-client.\nClients: claude-desktop, claude-code, cursor, codex; one and bridge provide manual setup.\n--no-service starts a detached node. Uninstall keeps your data; --purge removes ~/.weave data.\n';
+    const usage = 'joinweave [uninstall] [--yes] [--json] [--no-animation] [--no-service] [--no-mcp] [--path] [--mcp-client CLIENT] [--purge]\n\nInstalls native CLI, local identity, peer node, workspace and a persistent MCP server.\n--yes installs headlessly; PATH and MCP client edits require --path and --mcp-client.\nClients: claude-desktop, claude-code, cursor, codex; one and bridge provide manual setup.\n--no-mcp skips the MCP server and client setup. --no-animation disables terminal motion.\n--no-service starts a detached node. Uninstall keeps your data; --purge removes ~/.weave data.\n';
     console.log(options.json ? JSON.stringify({ ok: true, version: VERSION, usage }) : usage);
   } else if (options.version) console.log(options.json ? JSON.stringify({ ok: true, version: VERSION }) : VERSION);
   else {
-    if (!options.yes && !options.json && !process.stdin.isTTY && options.action === 'install') throw Object.assign(new Error('For unattended installation use --yes. MCP and PATH edits still need explicit flags.'), { code: 'INTERACTION_REQUIRED' });
+    if (!options.yes && !options.json && !process.stdin.isTTY && options.action === 'install') throw new InstallError('INTERACTION_REQUIRED', 'For unattended installation use --yes. MCP client and PATH edits still need explicit flags.');
+    presenter = new TerminalPresenter({ json: options.json, noAnimation: options.noAnimation });
     if (!options.yes && !options.json && process.stdin.isTTY) prompt = createInterface({ input: process.stdin, output: process.stderr });
+    process.once('SIGINT', onInt); process.once('SIGTERM', onTerm);
+    prompt?.once('SIGINT', onInt);
     const installer = new Installer({
       resolveNative: options.action === 'install' ? (await import('@useweave/cli')).resolveBinary : undefined,
-      confirm: async (question) => prompt ? /^y(?:es)?$/i.test((await prompt.question(`${question} [y/N] `)).trim()) : false,
-      progress: (message) => { if (!options.json) console.error(`✓ ${message}`); },
+      signal: controller.signal,
+      confirm: async (question) => {
+        if (!prompt) return false;
+        presenter.pause();
+        try { return /^y(?:es)?$/i.test((await prompt.question(`${question} [y/N] `, { signal: controller.signal })).trim()); }
+        finally { if (!controller.signal.aborted) presenter.resume(); }
+      },
+      stage: (stage) => {
+        if (controller.signal.aborted) throw new InstallError('INSTALL_INTERRUPTED', 'Installation interrupted. Your identity and recoverable installed components were preserved; rerun to continue.');
+        presenter.stage(stage);
+      },
+      progress: (message) => presenter.progress(message),
     });
     const result = await installer[options.action](options);
+    presenter.finish();
     if (options.json) console.log(JSON.stringify(result));
     else if (options.action === 'install') {
-      console.log(`\nWeave is ready.\nWorkspace: ${result.shared}\nTry: ${result.pathAdded ? 'weave doctor' : `${result.binary} doctor`}\n`);
+      console.log(`\n${installationSummary(result)}\n`);
       for (const manual of result.manualMcpClients) console.log(`${manual.client}: add this MCP server in the client's settings:\n${JSON.stringify({ weave: manual.server }, null, 2)}\n`);
-    }
-    else {
+    } else {
       console.log(result.ok ? `Weave uninstalled. ${result.dataRetained ? 'Your data is preserved.' : 'Workspace data removed.'} Your ~/Weave folder is preserved.` : 'Uninstall preserved modified files.');
       for (const warning of result.warnings) console.error(warning);
     }
     if (!result.ok) process.exitCode = 1;
   }
 } catch (error) {
-  const result = { ok: false, error: { code: error.code || 'INSTALL_FAILED', message: error.message } };
+  presenter?.finish();
+  const result = { ok: false, error: interrupted
+    ? { code: 'INSTALL_INTERRUPTED', message: 'Installation interrupted. Your identity and recoverable installed components were preserved; rerun to continue.' }
+    : { code: error.code || 'INSTALL_FAILED', message: error.message } };
   if (jsonRequested) console.log(JSON.stringify(result));
-  else console.error(`joinweave: ${error.message}`);
-  process.exitCode = 1;
-} finally { prompt?.close(); }
+  else console.error(`joinweave: ${result.error.message}`);
+  process.exitCode = interrupted === 'SIGINT' ? 130 : interrupted === 'SIGTERM' ? 143 : 1;
+} finally {
+  presenter?.finish(); prompt?.close();
+  process.removeListener('SIGINT', onInt); process.removeListener('SIGTERM', onTerm);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "joinweave",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
   "description": "One command to join the Weave agent-native web.",
   "license": "MIT OR Apache-2.0",

package/src/installer.js

@@ -1,10 +1,11 @@
 import * as fs from 'node:fs';
 import { homedir, hostname } from 'node:os';
-import { resolve, join, dirname, isAbsolute, parse } from 'node:path';
+import { resolve, join, dirname, basename, isAbsolute, parse } from 'node:path';
 import { createHash, randomUUID } from 'node:crypto';
 import { execFile } from 'node:child_process';
+import { ManagedMcp } from './managed-mcp.js';
 
-export const VERSION = '0.1.1';
+export const VERSION = '0.1.2';
 const NATIVE_PACKAGE_VERSION = '0.1.0';
 // Published native0.1.0 treats this as its service-ownership protocol version.
 const RECEIPT_VERSION = '0.1.0';
@@ -24,7 +25,7 @@ const digest = (bytes) => createHash('sha256').update(bytes).digest('hex');
 const regular = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
 
 export function parseArgs(args) {
-  const options = { action: 'install', yes: false, json: false, noService: false, noMcp: false, path: false, purge: false, mcpClients: [] };
+  const options = { action: 'install', yes: false, json: false, noService: false, noMcp: false, noAnimation: false, path: false, purge: false, mcpClients: [] };
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
     if (arg === 'uninstall' && i === 0) options.action = 'uninstall';
@@ -32,6 +33,7 @@ export function parseArgs(args) {
     else if (arg === '--json') options.json = true;
     else if (arg === '--no-service') options.noService = true;
     else if (arg === '--no-mcp') options.noMcp = true;
+    else if (arg === '--no-animation') options.noAnimation = true;
     else if (arg === '--path') options.path = true;
     else if (arg === '--purge') options.purge = true;
     else if (arg === '--help' || arg === '-h') options.help = true;
@@ -114,10 +116,58 @@ function unlinkIfUnchanged(path, expectedHash) {
   return true;
 }
 
-export function runCommand(command, args, { env = process.env, timeout = 60_000 } = {}) {
-  return new Promise((done) => execFile(command, args, { env, timeout, maxBuffer: 2 * 1024 * 1024, encoding: 'utf8', shell: false }, (error, stdout, stderr) => {
-    done({ code: error ? (typeof error.code === 'number' ? error.code : 1) : 0, stdout, stderr });
-  }));
+/** Callback errors can precede close. Ownership is released only after close. */
+export function runCommand(command, args, { env = process.env, timeout = 60_000, cwd, signal } = {}) {
+  return new Promise((done) => {
+    let child, stdout = '', stderr = '', error, closed = false, settled = false;
+    let deadlineTimer, killTimer, closeTimer, stopping = false;
+    const finish = (confirmed) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(deadlineTimer); clearTimeout(killTimer); clearTimeout(closeTimer);
+      signal?.removeEventListener('abort', cancel);
+      const result = { code: error || stopping ? (typeof error?.code === 'number' ? error.code : 1) : (child?.exitCode ?? 1), stdout, stderr, terminationConfirmed: confirmed };
+      if (!confirmed) {
+        result.childPid = child?.pid;
+        // Keep the persistent lock/stage, but allow the reporting installer to
+        // exit. A future installer checks the recorded child's liveness too.
+        child?.unref(); child?.stdout?.destroy(); child?.stderr?.destroy();
+      }
+      done(result);
+    };
+    const stop = (reason) => {
+      if (settled || stopping) return;
+      stopping = true; error ||= Object.assign(new Error(reason), { code: reason });
+      if (closed) { finish(true); return; }
+      child?.kill('SIGTERM');
+      killTimer = setTimeout(() => { if (!closed) child?.kill('SIGKILL'); }, 500);
+      closeTimer = setTimeout(() => finish(closed), 3_000);
+    };
+    const cancel = () => stop('ABORT_ERR');
+    if (signal?.aborted) { done({ code: 1, stdout, stderr, terminationConfirmed: true }); return; }
+    try {
+      // Lifecycle/timeout are owned here rather than execFile's early abort
+      // callback. No shell, and no lifecycle script descendants for MCP npm.
+      child = execFile(command, args, { env, cwd, maxBuffer: 2 * 1024 * 1024, encoding: 'utf8', shell: false }, (failure, out, err) => {
+        error ||= failure; stdout = out || ''; stderr = err || '';
+        if (failure && !closed && child?.exitCode === null && child?.signalCode === null) stop('COMMAND_ERROR');
+      });
+      child.once('close', () => { closed = true; finish(true); });
+      child.once('error', (failure) => { error ||= failure; stop('SPAWN_ERROR'); });
+      signal?.addEventListener('abort', cancel, { once: true });
+      if (signal?.aborted) cancel();
+      else deadlineTimer = setTimeout(() => stop('ETIMEDOUT'), Math.max(1, timeout));
+    } catch (failure) { error = failure; finish(true); }
+  });
+}
+
+function abortableSleep(ms, signal) {
+  return new Promise((done, reject) => {
+    if (signal?.aborted) { reject(new InstallError('INSTALL_INTERRUPTED', 'Installation interrupted.')); return; }
+    const abort = () => { clearTimeout(timer); reject(new InstallError('INSTALL_INTERRUPTED', 'Installation interrupted.')); };
+    const timer = setTimeout(() => { signal?.removeEventListener('abort', abort); done(); }, ms);
+    signal?.addEventListener('abort', abort, { once: true });
+  });
 }
 
 const xml = (value) => value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;').replaceAll("'", '&apos;');
@@ -127,7 +177,7 @@ const systemdPath = (value) => value.replaceAll('%', '%%');
 const shellQuote = (value) => `'${value.replaceAll("'", "'\\''")}'`;
 
 export class Installer {
-  constructor({ home = homedir(), weaveHome = process.env.WEAVE_HOME || join(home, '.weave'), platform = process.platform, uid = process.getuid?.(), env = process.env, run = runCommand, resolveNative, confirm = async () => false, progress = () => {}, sleep = (ms) => new Promise((done) => setTimeout(done, ms)), now = Date.now } = {}) {
+  constructor({ home = homedir(), weaveHome = process.env.WEAVE_HOME || join(home, '.weave'), platform = process.platform, uid = process.getuid?.(), env = process.env, run = runCommand, resolveNative, confirm = async () => false, progress = () => {}, stage = () => {}, signal, nodePath = process.execPath, npmCli, sleep = abortableSleep, now = Date.now } = {}) {
     this.home = resolve(home);
     this.weaveHome = resolve(weaveHome);
     if ([this.home, this.weaveHome].some((path) => /[\x00-\x1f\x7f]/.test(path))) fail('UNSAFE_PATH', 'Workspace and home paths cannot contain control characters.');
@@ -137,10 +187,29 @@ export class Installer {
     this.platform = platform;
     this.uid = uid;
     this.env = { ...env, WEAVE_HOME: this.weaveHome };
-    this.run = run;
+    this.run = async (...args) => {
+      const result = await run(...args);
+      if (result.terminationConfirmed === false) {
+        this.preserveLock = true;
+        if (Number.isInteger(result.childPid) && result.childPid > 0 && this.lockBytes) {
+          const owner = JSON.parse(this.lockBytes);
+          owner.children = [...new Set([...(owner.children || []), result.childPid])];
+          const next = Buffer.from(JSON.stringify(owner));
+          atomicWrite(this.lockPath, next, { previous: this.lockBytes });
+          this.lockBytes = next;
+        }
+        fail('CHILD_TERMINATION_UNCONFIRMED', 'Could not confirm installer subprocess termination. Its persistent lock, MCP staging tree and installed data were preserved. Do not remove the lock while its recorded process is alive.');
+      }
+      return result;
+    };
     this.resolveNative = resolveNative;
     this.confirm = confirm;
     this.progress = progress;
+    this.stage = stage;
+    this.signal = signal;
+    this.nodePath = nodePath;
+    this.npmCli = npmCli;
+    this.mcpRuntime = new ManagedMcp(this);
     this.sleep = sleep;
     this.now = now;
     this.binary = join(this.weaveHome, 'bin', 'weave');
@@ -177,8 +246,10 @@ export class Installer {
       let owner;
       try { owner = JSON.parse(old); } catch { fail('INSTALL_LOCKED', 'An unrecognized installer lock exists. It will not be removed automatically.'); }
       if (owner.host !== hostname() || !Number.isInteger(owner.pid) || owner.pid < 1) fail('INSTALL_LOCKED', 'Another installer owns this workspace.');
-      let alive = true;
-      try { process.kill(owner.pid, 0); } catch (error) { if (error.code === 'ESRCH') alive = false; }
+      if (owner.children !== undefined && (!Array.isArray(owner.children) || owner.children.some((pid) => !Number.isInteger(pid) || pid < 1))) fail('INSTALL_LOCKED', 'Installer lock has an unrecognized subprocess owner.');
+      const alive = [owner.pid, ...(owner.children || [])].some((pid) => {
+        try { process.kill(pid, 0); return true; } catch (error) { return error.code !== 'ESRCH'; }
+      });
       if (alive) fail('INSTALL_LOCKED', 'Another installer is running in this workspace.');
       if (!unlinkIfUnchanged(this.lockPath, digest(old))) fail('INSTALL_LOCKED', 'Installer lock changed; rerun after the other installer finishes.');
     }
@@ -187,11 +258,12 @@ export class Installer {
   }
 
   unlock() {
-    if (this.lockBytes) unlinkIfUnchanged(this.lockPath, digest(this.lockBytes));
+    if (this.lockBytes && !this.preserveLock) unlinkIfUnchanged(this.lockPath, digest(this.lockBytes));
   }
 
   async native(args, label, timeout = 60_000) {
-    const result = await this.run(this.binary, args, { env: this.env, timeout });
+    if (this.signal?.aborted) fail('INSTALL_INTERRUPTED', 'Installation interrupted.');
+    const result = await this.run(this.binary, args, { env: this.env, timeout, signal: this.signal });
     if (result.code !== 0) fail('NATIVE_COMMAND_FAILED', `${label} failed (exit ${result.code}). Run ${this.binary} ${args.join(' ')} to inspect the runtime result.`);
     let data;
     try { data = JSON.parse(result.stdout); } catch { fail('INVALID_NATIVE_RESULT', `${label} did not return valid JSON.`); }
@@ -204,8 +276,9 @@ export class Installer {
     for (let attempt = 0; ; attempt++) {
       try { return await this.native(['doctor', '--json'], 'Weave doctor', 90_000); }
       catch (error) {
+        if (this.signal?.aborted) fail('INSTALL_INTERRUPTED', 'Installation interrupted.');
         if (!['NATIVE_COMMAND_FAILED', 'NATIVE_CHECK_FAILED'].includes(error.code) || attempt >= 9 || Date.now() >= deadline) throw error;
-        await this.sleep(1_000);
+        await this.sleep(1_000, this.signal);
       }
     }
   }
@@ -243,7 +316,7 @@ export class Installer {
 
   async serviceCommand(args, required = true, timeout = 30_000) {
     const command = this.platform === 'darwin' ? 'launchctl' : 'systemctl';
-    const result = await this.run(command, args, { env: this.env, timeout });
+    const result = await this.run(command, args, { env: this.env, timeout, signal: this.signal });
     if (required && result.code !== 0) fail('SERVICE_COMMAND_FAILED', `${command} ${args.join(' ')} failed. Confirm a logged-in user service session is available; use --no-service for a detached node.`);
     return result;
   }
@@ -264,7 +337,7 @@ export class Installer {
           if (status.code !== 113 || !status.stderr.includes(missing)) fail('SERVICE_STOP_UNKNOWN', 'Could not verify launchd shutdown. Its binary and configuration were preserved.');
           break;
         }
-        await this.sleep(Math.min(100, deadline - checkedAt));
+        await this.sleep(Math.min(100, deadline - checkedAt), this.signal);
       }
     } else {
       await this.serviceCommand(['--user', 'disable', '--now', 'weave-node.service'], false);
@@ -341,12 +414,36 @@ export class Installer {
     return detected;
   }
 
-  mcpDefinition() {
+  legacyMcpDefinition() {
     return { command: 'npx', args: ['--yes', '@useweave/mcp@0.1.0'], env: { WEAVE_HOME: this.weaveHome, WEAVE_BINARY: this.binary } };
   }
 
-  mcpTomlBlock() {
-    return `${MCP_BEGIN}\n[mcp_servers.weave]\ncommand = "npx"\nargs = ["--yes", "@useweave/mcp@0.1.0"]\n\n[mcp_servers.weave.env]\nWEAVE_HOME = ${JSON.stringify(this.weaveHome)}\nWEAVE_BINARY = ${JSON.stringify(this.binary)}\n${MCP_END}\n`;
+  mcpDefinition() {
+    return { command: this.nodePath, args: [this.mcpRuntime.entry], env: { WEAVE_HOME: this.weaveHome, WEAVE_BINARY: this.binary } };
+  }
+
+  mcpTomlBlock(spec = this.mcpDefinition()) {
+    return `${MCP_BEGIN}\n[mcp_servers.weave]\ncommand = ${JSON.stringify(spec.command)}\nargs = [${spec.args.map((arg) => JSON.stringify(arg)).join(', ')}]\n\n[mcp_servers.weave.env]\nWEAVE_HOME = ${JSON.stringify(this.weaveHome)}\nWEAVE_BINARY = ${JSON.stringify(this.binary)}\n${MCP_END}\n`;
+  }
+
+  recognizedMcpReceipt(receipt) {
+    if (receipt.format === 'json') {
+      const spec = receipt.spec;
+      if (JSON.stringify(spec) === JSON.stringify(this.legacyMcpDefinition())) return true;
+      return regular(spec) && Object.keys(spec).sort().join(',') === 'args,command,env'
+        && typeof spec.command === 'string' && isAbsolute(spec.command) && ['node', 'nodejs'].includes(basename(spec.command)) && !/[\x00-\x1f\x7f]/.test(spec.command)
+        && JSON.stringify(spec.args) === JSON.stringify([this.mcpRuntime.entry])
+        && JSON.stringify(spec.env) === JSON.stringify({ WEAVE_HOME: this.weaveHome, WEAVE_BINARY: this.binary });
+    }
+    if (receipt.format !== 'toml' || typeof receipt.block !== 'string') return false;
+    if (receipt.block === this.mcpTomlBlock(this.legacyMcpDefinition())) return true;
+    // Parse only the JSON-encoded command line in our exact generated block.
+    // Everything else must equal the regenerated fixed entry/environment.
+    const line = receipt.block.match(/^command = (.+)$/m);
+    if (!line) return false;
+    let command; try { command = JSON.parse(line[1]); } catch { return false; }
+    return typeof command === 'string' && isAbsolute(command) && ['node', 'nodejs'].includes(basename(command)) && !/[\x00-\x1f\x7f]/.test(command)
+      && receipt.block === this.mcpTomlBlock({ ...this.mcpDefinition(), command });
   }
 
   installMcp(client) {
@@ -363,7 +460,7 @@ export class Installer {
       if (!regular(config) || (config.mcpServers !== undefined && !regular(config.mcpServers))) fail('INVALID_CLIENT_CONFIG', `${client} config has an unsupported MCP structure. It will not be changed.`);
       config.mcpServers ||= {};
       if (Object.hasOwn(config.mcpServers, 'weave')) {
-        if (!previous || previous.path !== path || JSON.stringify(previous.spec) !== JSON.stringify(spec) || JSON.stringify(config.mcpServers.weave) !== JSON.stringify(previous.spec)) fail('MCP_ENTRY_CONFLICT', `${client} already has an unrelated or modified weave MCP entry. It will not be changed.`);
+        if (!previous || previous.path !== path || !this.recognizedMcpReceipt(previous) || JSON.stringify(config.mcpServers.weave) !== JSON.stringify(previous.spec)) fail('MCP_ENTRY_CONFLICT', `${client} already has an unrelated or modified weave MCP entry. It will not be changed.`);
       }
       config.mcpServers.weave = spec;
       bytes = Buffer.from(`${JSON.stringify(config, null, 2)}\n`);
@@ -372,8 +469,8 @@ export class Installer {
       const text = old?.toString('utf8') || '';
       const block = this.mcpTomlBlock();
       let next = text;
-      if (previous?.path === path && previous.block !== block) fail('INVALID_MANIFEST', 'The Codex MCP receipt is not a recognized Weave server definition.');
-      if (previous?.path === path && text.includes(block)) next = text.replace(block, '');
+      if (previous?.path === path && !this.recognizedMcpReceipt(previous)) fail('INVALID_MANIFEST', 'The Codex MCP receipt is not a recognized Weave server definition.');
+      if (previous?.path === path && text.includes(previous.block)) next = text.replace(previous.block, '');
       // Do not guess at inline/quoted TOML tables or overwrite foreign definitions.
       if (/^\s*\[\[?\s*(?:mcp_servers|["']mcp_servers["'])\s*\./m.test(next) && /^\s*\[\[?\s*(?:mcp_servers|["']mcp_servers["'])\s*\.\s*(?:weave|["']weave["'])\s*(?:\.|\])/m.test(next)) fail('MCP_ENTRY_CONFLICT', 'Codex already has a weave MCP table. It will not be changed.');
       if (next.includes(MCP_BEGIN) || next.includes(MCP_END) || /^\s*(?:mcp_servers|["']mcp_servers["'])\s*=/m.test(next) || /^\s*\[\s*(?:mcp_servers|["']mcp_servers["'])\s*\]\s*$/m.test(next)) fail('INVALID_CLIENT_CONFIG', 'Codex config uses a structure that cannot be merged safely. Add the Weave MCP entry manually.');
@@ -392,20 +489,30 @@ export class Installer {
     this.lock();
     try {
       this.loadManifest();
+      this.stage({ id: 'runtime', label: 'Installing the native runtime' });
       this.installBinary();
       ensureDirectory(this.shared, 0o755);
-      await this.native(['init', '--json'], 'Workspace initialization');
+      this.stage({ id: 'identity', label: 'Opening your workspace and local identity' });
+      const initialized = await this.native(['init', '--json'], 'Workspace initialization');
       this.progress('Created your workspace and identity');
+      this.stage({ id: 'node', label: options.noService ? 'Starting your peer node' : 'Starting your supervised peer node' });
       if (options.noService) {
         // A rerun switching off service management must not leave two runtime owners.
         if (this.manifest.service) await this.removeService();
         if (this.manifest.service) fail('MODIFIED_SERVICE', 'The modified service was preserved. Stop and remove it before starting a detached node.');
         await this.native(['node', 'start', '--json'], 'Detached node startup');
+        this.progress('Started the detached node');
       } else {
         // Stop an earlier detached runtime before the service takes ownership.
         await this.native(['node', 'stop', '--json'], 'Node shutdown before service startup');
         await this.installService();
       }
+      this.stage({ id: 'mcp', label: options.noMcp ? 'Keeping MCP installation disabled' : 'Installing the persistent MCP server' });
+      if (!options.noMcp) {
+        await this.mcpRuntime.install();
+        this.progress('Installed the MCP server');
+      } else this.progress('MCP installation skipped');
+      this.stage({ id: 'clients', label: 'Choosing your agent connections' });
       const detected = this.detectClients();
       if (options.path || (!options.yes && !options.json && await this.confirm('Add Weave to your shell PATH?'))) this.installPath();
       const selected = [...options.mcpClients];
@@ -414,9 +521,16 @@ export class Installer {
       }
       for (const client of selected) this.installMcp(client);
       // Doctor owns connectivity, peer and announce/find validation. Never turn a failed doctor into success.
+      this.stage({ id: 'verify', label: 'Verifying live peer connectivity' });
       const doctor = await this.readyDoctor();
       this.progress('Verified Weave connectivity');
-      return { ok: true, action: 'install', version: VERSION, binary: this.binary, workspace: this.weaveHome, shared: this.shared, service: { managed: !options.noService, running: true }, pathAdded: Boolean(this.manifest.path), mcpClients: Object.keys(this.manifest.mcp), detectedMcpClients: detected, manualMcpClients: this.manualMcp, doctor, next: this.manifest.path ? 'weave doctor' : `${this.binary} doctor` };
+      return { ok: true, action: 'install', version: VERSION, binary: this.binary, workspace: this.weaveHome, shared: this.shared, service: { managed: !options.noService, running: true }, pathAdded: Boolean(this.manifest.path), mcpClients: Object.keys(this.manifest.mcp), detectedMcpClients: detected, manualMcpClients: this.manualMcp, doctor, components: [
+        { id: 'runtime', name: 'Native CLI', version: NATIVE_PACKAGE_VERSION, status: 'installed', path: this.binary },
+        { id: 'identity', name: 'Local identity', status: 'ready', localOnly: true },
+        { id: 'node', name: 'Peer node', status: 'running', managed: !options.noService },
+        { id: 'workspace', name: 'Workspace', status: 'ready', path: this.shared },
+        { id: 'mcp', name: 'Agent MCP server', version: NATIVE_PACKAGE_VERSION, status: options.noMcp ? 'skipped' : 'installed', ...(options.noMcp ? {} : { command: this.nodePath, entry: this.mcpRuntime.entry }) },
+      ], initialization: initialized, next: this.manifest.path ? 'weave doctor' : `${this.binary} doctor` };
     } finally { this.unlock(); }
   }
 
@@ -454,7 +568,7 @@ export class Installer {
     if (!clients.has(client)) fail('INVALID_MANIFEST', 'Unknown MCP client in the installation receipt.');
     const receipt = this.manifest.mcp[client], expected = this.clientDefinition(client);
     if (receipt.path !== expected.path || receipt.format !== expected.format) fail('INVALID_MANIFEST', 'MCP receipt does not match this user.');
-    if (expected.format === 'json' && JSON.stringify(receipt.spec) !== JSON.stringify(this.mcpDefinition())) fail('INVALID_MANIFEST', 'MCP receipt is not a recognized Weave server definition.');
+    if (!this.recognizedMcpReceipt(receipt)) fail('INVALID_MANIFEST', 'MCP receipt is not a recognized Weave server definition.');
     const old = readFile(expected.path);
     if (old) {
       let bytes;
@@ -469,7 +583,7 @@ export class Installer {
         }
       } else {
         const text = old.toString('utf8');
-        if (receipt.block !== this.mcpTomlBlock()) fail('INVALID_MANIFEST', 'MCP block receipt is not a recognized Weave server definition.');
+        if (!this.recognizedMcpReceipt(receipt)) fail('INVALID_MANIFEST', 'MCP block receipt is not a recognized Weave server definition.');
         if (!text.includes(receipt.block)) { this.warnings.push('Preserved modified Codex weave MCP entry.'); return; }
         bytes = Buffer.from(text.replace(receipt.block, ''));
       }
@@ -489,6 +603,7 @@ export class Installer {
       this.loadManifest();
       const known = readFile(this.manifestPath);
       if (!known) fail('NO_INSTALL_RECEIPT', 'No joinweave installation receipt exists. Existing files will not be removed.');
+      this.stage({ id: 'node', label: 'Stopping the owned background node' });
       await this.removeService();
       if (this.manifest.service) fail('MODIFIED_SERVICE', 'The modified service was preserved. Stop and remove it before uninstalling the binary.');
       const binary = readFile(this.binary);
@@ -500,6 +615,8 @@ export class Installer {
       } else if (binary) this.warnings.push('Preserved unrelated or modified executable.');
       this.removePath();
       for (const client of Object.keys(this.manifest.mcp)) this.removeMcp(client);
+      this.stage({ id: 'mcp', label: 'Removing owned tools and connections' });
+      this.mcpRuntime.remove();
       if (options.purge && this.warnings.length) fail('PURGE_BLOCKED', 'Modified installer entries were preserved. Resolve them before purging workspace data.');
       if (!this.warnings.length) {
         const receipt = readFile(this.manifestPath);

package/src/managed-mcp.js

@@ -0,0 +1,143 @@
+import * as fs from 'node:fs';
+import { join, dirname, resolve, isAbsolute } from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { InstallError, assertSafePath } from './installer.js';
+
+export const MCP_VERSION = '0.1.0';
+export const MCP_INTEGRITY = 'sha512-l5i5RCgWYSZYtwXWF9AG0Bgpz6X9jcDQFYq4lzlioXkD3ZYYfs0Gxw44D+jLYAae/Dq22CGVKScA6MQRBP7RDg==';
+const ENTRY = 'node_modules/@useweave/mcp/bin/weave-mcp.js';
+const sha = (bytes) => createHash('sha256').update(bytes).digest('hex');
+const fail = (code, message) => { throw new InstallError(code, message); };
+
+/** No links, sockets or special files; bounded, private, immutable runtime tree. */
+export function censusTree(root) {
+  assertSafePath(root);
+  if (!fs.lstatSync(root).isDirectory()) fail('UNSAFE_MCP_TREE', 'MCP runtime is not a directory.');
+  const files = []; let size = 0;
+  const visit = (relative) => {
+    const path = join(root, relative), stat = fs.lstatSync(path);
+    if (stat.isSymbolicLink() || (!stat.isDirectory() && !stat.isFile())) fail('UNSAFE_MCP_TREE', `MCP runtime contains an unsupported file: ${relative}.`);
+    if (files.length >= 20_000) fail('MCP_TREE_LIMIT', 'MCP runtime exceeds the file limit.');
+    if (stat.isDirectory()) {
+      files.push({ path: relative, type: 'directory', mode: stat.mode & 0o777 });
+      for (const name of fs.readdirSync(path).sort()) visit(relative ? `${relative}/${name}` : name);
+    } else {
+      size += stat.size;
+      if (size > 128 * 1024 * 1024) fail('MCP_TREE_LIMIT', 'MCP runtime exceeds the size limit.');
+      files.push({ path: relative, type: 'file', mode: stat.mode & 0o777, size: stat.size, sha256: sha(fs.readFileSync(path)) });
+    }
+  };
+  visit('');
+  return files;
+}
+
+export function resolveNpmCli(env, nodePath) {
+  const named = env.npm_execpath;
+  const candidates = [named && join(dirname(named), 'npm-cli.js'), join(dirname(nodePath), '..', 'lib', 'node_modules', 'npm', 'bin', 'npm-cli.js')].filter(Boolean);
+  for (const candidate of candidates) {
+    if (!isAbsolute(candidate)) continue;
+    try {
+      const path = fs.realpathSync(candidate);
+      if (fs.statSync(path).isFile() && path.endsWith('/npm-cli.js')) return path;
+    } catch { /* Try the npm distribution next to Node. */ }
+  }
+  fail('NPM_UNAVAILABLE', 'Cannot locate npm beside Node. Run this installer through npx, or use --no-mcp.');
+}
+
+export function verifyMcpTree(root) {
+  const files = censusTree(root);
+  const pkg = JSON.parse(fs.readFileSync(join(root, 'node_modules/@useweave/mcp/package.json'), 'utf8'));
+  const lock = JSON.parse(fs.readFileSync(join(root, 'package-lock.json'), 'utf8'));
+  const top = lock.packages?.['node_modules/@useweave/mcp'];
+  if (pkg.name !== '@useweave/mcp' || pkg.version !== MCP_VERSION || pkg.bin?.['weave-mcp'] !== 'bin/weave-mcp.js' || top?.version !== MCP_VERSION || top?.integrity !== MCP_INTEGRITY || !files.some((file) => file.path === ENTRY && file.type === 'file')) fail('INVALID_MCP_PACKAGE', 'MCP package does not match the pinned published release.');
+  for (const [path, entry] of Object.entries(lock.packages || {})) {
+    if (!path) continue;
+    if (entry.link || !/^https:\/\/registry\.npmjs\.org\//.test(entry.resolved || '') || !/^sha512-[A-Za-z0-9+/]+={0,2}$/.test(entry.integrity || '')) fail('INVALID_MCP_LOCK', 'MCP dependency lock contains an unverified package source.');
+  }
+  return files;
+}
+
+export class ManagedMcp {
+  constructor(installer) {
+    this.owner = installer;
+    this.path = join(installer.weaveHome, 'tools', `mcp-${MCP_VERSION}`);
+    this.entry = join(this.path, ENTRY);
+  }
+
+  validReceipt(receipt) {
+    return receipt && receipt.version === MCP_VERSION && receipt.path === this.path && receipt.entry === this.entry && Array.isArray(receipt.files);
+  }
+
+  unchanged(receipt) {
+    return this.validReceipt(receipt) && JSON.stringify(censusTree(this.path)) === JSON.stringify(receipt.files);
+  }
+
+  async install() {
+    const owner = this.owner;
+    let receipt = owner.manifest.mcpRuntime;
+    assertSafePath(this.path);
+    if (receipt?.staging) {
+      if (!this.validReceipt(receipt) || dirname(receipt.staging) !== dirname(this.path) || !/^\.mcp-[a-f0-9-]{36}\.staging$/.test(receipt.staging.split('/').pop())) fail('INVALID_MANIFEST', 'MCP staging receipt is not recognized.');
+      assertSafePath(receipt.staging);
+      if (fs.existsSync(receipt.staging)) {
+        if (fs.existsSync(this.path)) fail('CONCURRENT_EDIT', 'Both staged and installed MCP runtimes exist. They were preserved.');
+        if (JSON.stringify(verifyMcpTree(receipt.staging)) !== JSON.stringify(receipt.files)) fail('UNMANAGED_MCP_RUNTIME', 'The recoverable MCP stage was modified. It was preserved.');
+        fs.renameSync(receipt.staging, this.path);
+      } else if (!fs.existsSync(this.path)) {
+        delete owner.manifest.mcpRuntime;
+        owner.saveManifest();
+        receipt = undefined;
+      }
+      if (receipt) {
+        if (!this.unchanged(receipt)) fail('UNMANAGED_MCP_RUNTIME', 'The recoverable MCP runtime was modified. It was preserved.');
+        delete receipt.staging;
+        owner.saveManifest();
+      }
+    }
+    if (fs.existsSync(this.path)) {
+      if (!this.unchanged(receipt)) fail('UNMANAGED_MCP_RUNTIME', `An unrelated or modified MCP runtime exists at ${this.path}. It was preserved.`);
+      verifyMcpTree(this.path);
+      return;
+    }
+    if (receipt) fail('MISSING_MCP_RUNTIME', 'The recorded MCP runtime is missing. Uninstall the owned receipt before reinstalling.');
+    assertSafePath(dirname(this.path));
+    fs.mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 });
+    const stage = join(dirname(this.path), `.mcp-${randomUUID()}.staging`);
+    fs.mkdirSync(stage, { mode: 0o700 });
+    try {
+      fs.writeFileSync(join(stage, 'package.json'), JSON.stringify({ name: 'joinweave-managed-mcp', version: MCP_VERSION, private: true, dependencies: { '@useweave/mcp': MCP_VERSION } }), { flag: 'wx', mode: 0o600 });
+      const npmCli = owner.npmCli || resolveNpmCli(owner.env, owner.nodePath);
+      const result = await owner.run(owner.nodePath, [npmCli, 'install', '--prefix', stage, '--ignore-scripts', '--bin-links=false', '--omit=optional', '--no-audit', '--no-fund', '--save-exact', '--registry=https://registry.npmjs.org', '--loglevel=error'], { env: owner.env, cwd: stage, timeout: 180_000, signal: owner.signal });
+      if (result.code !== 0) fail('MCP_INSTALL_FAILED', `MCP installation failed (exit ${result.code}). Your runtime and identity remain available. Check npm connectivity and its existing release-age policy, then rerun.`);
+      const files = verifyMcpTree(stage);
+      assertSafePath(this.path);
+      if (fs.existsSync(this.path)) fail('CONCURRENT_EDIT', 'MCP destination appeared during installation. It was not replaced.');
+      // Journal the exact verified stage before rename, so an interruption at
+      // either side of the atomic commit remains recoverable without guessing.
+      owner.manifest.mcpRuntime = { version: MCP_VERSION, path: this.path, entry: this.entry, files, staging: stage };
+      owner.saveManifest();
+      fs.renameSync(stage, this.path);
+      delete owner.manifest.mcpRuntime.staging;
+      owner.saveManifest();
+    } finally {
+      // Only this process's exclusive random staging directory; never a receipt path.
+      if (!owner.preserveLock && fs.existsSync(stage)) fs.rmSync(stage, { recursive: true });
+    }
+  }
+
+  remove() {
+    const owner = this.owner, receipt = owner.manifest.mcpRuntime;
+    if (!receipt) return;
+    if (!this.validReceipt(receipt)) fail('INVALID_MANIFEST', 'MCP runtime receipt is not recognized.');
+    if (receipt.staging) { owner.warnings.push('Preserved a recoverable MCP staging receipt. Rerun installation before uninstalling it.'); return; }
+    assertSafePath(this.path);
+    if (fs.existsSync(this.path)) {
+      if (owner.warnings.length || !this.unchanged(receipt)) { owner.warnings.push('Preserved modified or still-referenced MCP runtime.'); return; }
+      // Recheck the entire owned tree immediately before removing it.
+      if (!this.unchanged(receipt)) fail('CONCURRENT_EDIT', 'MCP runtime changed while preparing removal.');
+      fs.rmSync(this.path, { recursive: true });
+    }
+    delete owner.manifest.mcpRuntime;
+    owner.saveManifest();
+  }
+}

package/src/terminal.js

@@ -0,0 +1,158 @@
+const RESET = '\x1b[0m', HIDE = '\x1b[?25l', SHOW = '\x1b[?25h';
+const clean = (value) => String(value).replace(/[\x00-\x1f\x7f-\x9f]/g, '');
+const tint = (value, color, enabled) => enabled ? `\x1b[38;5;${color}m${value}${RESET}` : value;
+const stages = ['runtime', 'identity', 'node', 'mcp', 'clients', 'verify'];
+const glyphs = '.:-=+*#';
+
+/** A deterministic protocol illustration. Packets describe motion, never live telemetry. */
+export function fabricFrame(width, height, tick = 0, phase = 0, color = true) {
+  width = Math.max(24, Math.min(88, Math.floor(width)));
+  height = Math.max(8, Math.min(23, Math.floor(height)));
+  const cells = Array(width * height).fill(' '), depths = new Float64Array(width * height).fill(-Infinity), colors = new Uint8Array(width * height);
+  const angle = -0.48 + Math.sin(tick / 28) * 0.09, ca = Math.cos(angle), sa = Math.sin(angle);
+  const plot = (x, y, z, char, hue = 245) => {
+    const rx = x * ca + z * sa, rz = z * ca - x * sa;
+    const perspective = 1 / (1 - rz * 0.11);
+    const px = Math.round(width / 2 + rx * perspective * width * 0.19);
+    const py = Math.round(height / 2 - (y * 0.78 - rz * 0.29) * perspective * height * 0.31);
+    if (px < 0 || px >= width || py < 0 || py >= height) return;
+    const i = py * width + px;
+    if (rz < depths[i]) return;
+    depths[i] = rz; cells[i] = char; colors[i] = hue;
+  };
+  // Registration planes below, within and above the fabric.
+  for (const y of [-1.34, 0, 1.34]) {
+    for (let i = 0; i <= 70; i++) {
+      const p = i / 70 * 3.9 - 1.95;
+      plot(p, y, -1.08, '.', 240); plot(p, y, 1.08, '.', 240);
+      plot(-1.95, y, p * 0.55, '.', 240); plot(1.95, y, p * 0.55, '.', 240);
+    }
+  }
+  // Counter-wound filaments cross around a signed central spine.
+  const count = width < 50 ? 22 : 38;
+  for (let strand = 0; strand < count; strand++) {
+    const offset = strand / count * Math.PI * 2;
+    const handed = strand % 2 ? 1 : -1;
+    for (let i = 0; i < 100; i++) {
+      const t = i / 99, y = (t - 0.5) * 3.65;
+      const radius = 0.80 + 0.48 * Math.pow(Math.sin(t * Math.PI), 2);
+      const a = offset + t * Math.PI * 2.1 * handed;
+      const x = Math.cos(a) * radius, z = Math.sin(a) * radius;
+      const shade = glyphs[Math.round((z / radius + 1) * 0.5 * (glyphs.length - 1))];
+      const active = strand % 6 === phase % 6;
+      plot(x, y, z, shade, active ? (handed > 0 ? 81 : 141) : z > 0 ? 250 : 240);
+      if (active && Math.abs((t + strand * 0.037 - tick / 70) % 1) < 0.016) plot(x, y, z + 0.02, '@', 159);
+    }
+  }
+  // Individually composed peer modules, not a globe or starfield.
+  for (let i = 0; i < 18; i++) {
+    const a = i * 2.399963, y = (i % 6 - 2.5) * 0.52;
+    const x = Math.cos(a) * (1.50 + (i % 3) * 0.15), z = Math.sin(a) * 1.18;
+    const hue = i % 6 === phase % 6 ? 117 : 246;
+    plot(x - 0.10, y, z, '[', hue); plot(x, y, z, i % 3 === 0 ? '+' : ':', hue); plot(x + 0.10, y, z, ']', hue);
+  }
+  for (let i = 0; i < 7; i++) {
+    const y = (i - 3) * 0.45;
+    plot(-0.14, y, 1.33, '[', 147); plot(0, y, 1.34, phase === 1 || phase === 5 ? '#' : '=', 153); plot(0.14, y, 1.33, ']', 147);
+    if (i < 6) plot(0, y + 0.22, 1.32, '|', 245);
+  }
+  const lines = [];
+  for (let y = 0; y < height; y++) {
+    let line = '', last = -1;
+    for (let x = 0; x < width; x++) {
+      const i = y * width + x, hue = colors[i];
+      if (color && hue !== last) { line += hue ? `\x1b[38;5;${hue}m` : RESET; last = hue; }
+      line += cells[i];
+    }
+    lines.push(color ? `${line}${RESET}` : line);
+  }
+  return lines;
+}
+
+export class TerminalPresenter {
+  constructor({ stream = process.stderr, env = process.env, json = false, noAnimation = false, timers = globalThis } = {}) {
+    this.stream = stream; this.json = json; this.timers = timers;
+    this.color = !Object.hasOwn(env, 'NO_COLOR') && env.TERM !== 'dumb';
+    this.animated = !json && !noAnimation && Boolean(stream.isTTY) && env.TERM !== 'dumb';
+    this.active = false; this.closed = false; this.height = 0; this.tick = 0;
+    this.phase = 0; this.label = 'Preparing your developer runtime'; this.completed = [];
+    this.resize = () => { if (this.active) this.render(); };
+    if (this.animated) stream.on?.('resize', this.resize);
+  }
+  start() {
+    if (!this.animated || this.closed || this.active) return;
+    this.active = true;
+    this.stream.write(HIDE);
+    this.render();
+    this.timer = this.timers.setInterval(() => { this.tick++; this.render(); }, 120);
+    this.timer?.unref?.();
+  }
+  stage({ id, label }) {
+    this.phase = Math.max(0, stages.indexOf(id)); this.label = clean(label);
+    if (this.animated) { if (!this.active) this.start(); else this.render(); }
+    else if (!this.json && !this.closed) this.stream.write(`\n> ${this.label}\n`);
+  }
+  progress(message) {
+    const text = clean(message);
+    this.completed.push(text);
+    if (this.active) this.render();
+    else if (!this.json && !this.closed) this.stream.write(`  + ${text}\n`);
+  }
+  render() {
+    if (!this.active || this.closed) return;
+    const columns = Math.max(1, Math.floor(this.stream.columns || 80));
+    const width = Math.min(88, columns - 2), rows = Math.floor(this.stream.rows || 36);
+    // Tiny terminals use readable status, rather than clipping a sculpture.
+    const title = width >= 48 ? 'W E A V E   /   THE AGENT-NATIVE WEB' : 'W E A V E';
+    const lines = [tint(title.slice(0, columns - 1), 147, this.color)];
+    if (width >= 26 && rows >= 17) lines.push(...fabricFrame(width, Math.min(23, rows - 11), this.tick, this.phase, this.color));
+    lines.push('', tint(this.label.slice(0, columns - 1), 159, this.color));
+    const trace = stages.map((id, i) => i === this.phase ? `[${id}]` : id).join(' / ');
+    if (trace.length < columns) lines.push(tint(trace, 245, this.color));
+    const recent = this.completed.slice(-2);
+    for (const message of recent) lines.push(`+ ${message}`.slice(0, columns - 1));
+    if (width >= 44) lines.push(tint('Protocol illustration  |  real installation stages'.slice(0, columns - 1), 240, this.color));
+    if (rows < 7) lines.splice(0, lines.length, tint(this.label.slice(0, columns - 1), 159, this.color));
+    this.clear();
+    for (const line of lines) this.stream.write(`\r\x1b[2K${line}\n`);
+    this.widths = lines.map((line) => line.replace(/\x1b\[[0-9;]*m/g, '').length);
+    this.height = lines.length;
+  }
+  clear() {
+    if (!this.height) return;
+    const columns = Math.max(1, Math.floor(this.stream.columns || 80));
+    const priorRows = this.widths?.reduce((sum, width) => sum + Math.max(1, Math.ceil(width / columns)), 0) || this.height;
+    // Reflow may put old illustration lines into scrollback. Clear only the
+    // currently visible owned region; never scroll a tall blank frame through
+    // a newly tiny terminal.
+    const height = Math.min(priorRows, Math.max(1, Math.floor(this.stream.rows || 36) - 1));
+    this.stream.write(`\x1b[${height}A`);
+    for (let i = 0; i < height; i++) this.stream.write('\r\x1b[2K\n');
+    this.stream.write(`\x1b[${height}A\r`);
+    this.height = 0;
+  }
+  pause() {
+    if (this.timer !== undefined) { this.timers.clearInterval(this.timer); this.timer = undefined; }
+    this.active = false;
+    if (this.animated) { this.clear(); this.stream.write(`${RESET}${SHOW}`); }
+  }
+  resume() { this.start(); }
+  finish() {
+    if (this.closed) return;
+    this.pause(); this.closed = true;
+    if (this.animated) this.stream.off?.('resize', this.resize);
+  }
+}
+
+const quote = (value) => `'${String(value).replaceAll("'", "'\\''")}'`;
+export function installationSummary(result) {
+  const cli = result.pathAdded ? 'weave' : quote(result.binary);
+  const lines = ['Weave is ready.', ''];
+  for (const component of result.components || []) {
+    const status = component.status === 'installed' || component.status === 'ready' ? '+' : component.status === 'running' ? '+' : '-';
+    lines.push(`${status} ${component.name}${component.version ? ` ${component.version}` : ''}  /  ${component.status}${component.id === 'node' ? ` (${component.managed ? 'user service' : 'detached'})` : ''}`);
+  }
+  lines.push('', `Workspace: ${result.shared}`, `Private identity and data: ${result.workspace}`, `Agent clients: ${result.mcpClients.length ? result.mcpClients.join(', ') : 'none configured; consent is required'}`, '', 'Your next thread:', `  ${cli} node status --json`, `  ${cli} strand create --json`, '', 'Docs: https://docs.weave.earth/getting-started/quickstart', 'Your identity stays local. No account or desktop app was installed.');
+  if (!result.pathAdded) lines.push('Add the CLI to PATH with a consented rerun: npx joinweave@0.1.2 --yes --path');
+  return lines.map(clean).join('\n');
+}