joinweave 0.0.0-stage → 0.1.0

package/LICENSE-APACHE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 L1fe AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,72 @@
-# Temporary Holding Version
+# joinweave
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The web wasn't built for agents. Weave was.
+
+```sh
+npx joinweave@0.1.0
+```
+
+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.
+
+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.
+
+For agents and unattended installs:
+
+```sh
+npx joinweave@0.1.0 --yes --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.
+
+Options:
+
+- `--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.
+
+For example, consent to Cursor and Codex configuration headlessly:
+
+```sh
+npx joinweave@0.1.0 --yes --path --mcp-client cursor,codex --json
+```
+
+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.
+
+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.
+
+```sh
+npx joinweave@0.1.0 uninstall --yes
+npx joinweave@0.1.0 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.

package/bin/joinweave.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import { createInterface } from 'node:readline/promises';
+import { Installer, VERSION, parseArgs } from '../src/installer.js';
+
+const jsonRequested = process.argv.slice(2).includes('--json');
+let prompt;
+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';
+    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) prompt = createInterface({ input: process.stdin, output: process.stderr });
+    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}`); },
+    });
+    const result = await installer[options.action](options);
+    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`);
+      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 {
+      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 } };
+  if (jsonRequested) console.log(JSON.stringify(result));
+  else console.error(`joinweave: ${error.message}`);
+  process.exitCode = 1;
+} finally { prompt?.close(); }

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "joinweave",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "description": "One command to join the Weave agent-native web.",
+  "license": "MIT OR Apache-2.0",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "joinweave": "bin/joinweave.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "dependencies": {
+    "@useweave/cli": "0.1.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/l1felabs/useweave.git",
+    "directory": "npm/joinweave"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  }
+}

package/src/installer.js

@@ -0,0 +1,503 @@
+import * as fs from 'node:fs';
+import { homedir, hostname } from 'node:os';
+import { resolve, join, dirname, isAbsolute, parse } from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { execFile } from 'node:child_process';
+
+export const VERSION = '0.1.0';
+const PATH_BEGIN = '# >>> joinweave managed PATH >>>';
+const PATH_END = '# <<< joinweave managed PATH <<<' ;
+const MCP_BEGIN = '# >>> joinweave managed MCP >>>';
+const MCP_END = '# <<< joinweave managed MCP <<<';
+const serviceName = 'com.useweave.node';
+const clients = new Set(['claude-desktop', 'claude-code', 'cursor', 'codex']);
+const manualClients = new Set(['one', 'bridge']);
+
+export class InstallError extends Error {
+  constructor(code, message) { super(message); this.code = code; }
+}
+function fail(code, message) { throw new InstallError(code, message); }
+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: [] };
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === 'uninstall' && i === 0) options.action = 'uninstall';
+    else if (arg === '--yes' || arg === '-y') options.yes = true;
+    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 === '--path') options.path = true;
+    else if (arg === '--purge') options.purge = true;
+    else if (arg === '--help' || arg === '-h') options.help = true;
+    else if (arg === '--version' || arg === '-v') options.version = true;
+    else if (arg === '--mcp-client' || arg.startsWith('--mcp-client=')) {
+      const value = arg.includes('=') ? arg.slice(arg.indexOf('=') + 1) : args[++i];
+      if (!value) fail('INVALID_ARGUMENT', '--mcp-client requires a client name.');
+      for (const client of value.split(',')) {
+        if (!clients.has(client) && !manualClients.has(client)) fail('INVALID_ARGUMENT', `Unknown MCP client ${client}. Choose claude-desktop, claude-code, cursor or codex; one and bridge provide manual setup.`);
+        if (!options.mcpClients.includes(client)) options.mcpClients.push(client);
+      }
+    } else fail('INVALID_ARGUMENT', `Unknown argument: ${arg}`);
+  }
+  if (options.purge && options.action !== 'uninstall') fail('INVALID_ARGUMENT', '--purge is only valid with uninstall.');
+  if (options.noMcp && options.mcpClients.length) fail('INVALID_ARGUMENT', '--no-mcp conflicts with --mcp-client.');
+  return options;
+}
+
+/** Reject symlinks at every existing path component, including broken links. */
+export function assertSafePath(path) {
+  if (!isAbsolute(path)) fail('UNSAFE_PATH', 'Installer paths must be absolute.');
+  const absolute = resolve(path), root = parse(absolute).root;
+  let cursor = root;
+  for (const part of absolute.slice(root.length).split('/').filter(Boolean)) {
+    cursor = join(cursor, part);
+    let stat;
+    try { stat = fs.lstatSync(cursor); }
+    catch (error) { if (error.code === 'ENOENT') return; throw error; }
+    if (stat.isSymbolicLink()) fail('UNSAFE_SYMLINK', `Refusing symbolic link at ${cursor}.`);
+    if (cursor !== absolute && !stat.isDirectory()) fail('UNSAFE_PATH', `Parent path is not a directory: ${cursor}.`);
+  }
+}
+
+function ensureDirectory(path, mode = 0o700) {
+  assertSafePath(path);
+  if (fs.existsSync(path)) {
+    if (!fs.lstatSync(path).isDirectory()) fail('UNSAFE_PATH', `Expected a directory at ${path}.`);
+    return;
+  }
+  const parent = dirname(path);
+  if (parent !== path) ensureDirectory(parent);
+  fs.mkdirSync(path, { mode });
+}
+
+function readFile(path) {
+  assertSafePath(path);
+  try {
+    const stat = fs.lstatSync(path);
+    if (!stat.isFile()) fail('UNSAFE_PATH', `Expected a regular file at ${path}.`);
+    return fs.readFileSync(path);
+  } catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+}
+
+/** Atomic, compare-before-replace edit. Backups stay beside edited app files. */
+function atomicWrite(path, bytes, { previous = null, mode = 0o600, backup = false } = {}) {
+  assertSafePath(path);
+  ensureDirectory(dirname(path));
+  const current = readFile(path);
+  if ((current === null) !== (previous === null) || (current && !current.equals(previous))) fail('CONCURRENT_EDIT', `The file changed while preparing an edit: ${path}. Rerun after the other editor finishes.`);
+  if (backup && current !== null) {
+    fs.writeFileSync(`${path}.joinweave-backup-${randomUUID()}`, current, { flag: 'wx', mode: 0o600 });
+  }
+  const temporary = join(dirname(path), `.joinweave-${randomUUID()}.new`);
+  try {
+    const fd = fs.openSync(temporary, 'wx', mode);
+    try { fs.writeFileSync(fd, bytes); fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
+    assertSafePath(path);
+    const latest = readFile(path);
+    if ((latest === null) !== (previous === null) || (latest && !latest.equals(previous))) fail('CONCURRENT_EDIT', `Refusing to replace a concurrently edited file: ${path}.`);
+    fs.renameSync(temporary, path);
+  } finally { if (fs.existsSync(temporary)) fs.unlinkSync(temporary); }
+}
+
+function unlinkIfUnchanged(path, expectedHash) {
+  const current = readFile(path);
+  if (!current) return true;
+  if (digest(current) !== expectedHash) return false;
+  assertSafePath(path);
+  fs.unlinkSync(path);
+  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 });
+  }));
+}
+
+const xml = (value) => value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;').replaceAll("'", '&apos;');
+const systemdQuote = (value, exec = false) => `"${value.replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('%', '%%').replaceAll('$', exec ? '$$' : '$')}"`;
+// Scalar path directives do not use ExecStart/Environment's token parser.
+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)) } = {}) {
+    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.');
+    if (!isAbsolute(weaveHome) || this.weaveHome === this.home || this.weaveHome === '/' || this.home.startsWith(`${this.weaveHome}/`)) fail('UNSAFE_HOME', 'WEAVE_HOME must be a dedicated absolute workspace directory.');
+    this.shared = join(this.home, 'Weave');
+    if (this.weaveHome === this.shared || this.shared.startsWith(`${this.weaveHome}/`)) fail('UNSAFE_HOME', 'WEAVE_HOME must be separate from the visible Weave folder.');
+    this.platform = platform;
+    this.uid = uid;
+    this.env = { ...env, WEAVE_HOME: this.weaveHome };
+    this.run = run;
+    this.resolveNative = resolveNative;
+    this.confirm = confirm;
+    this.progress = progress;
+    this.sleep = sleep;
+    this.binary = join(this.weaveHome, 'bin', 'weave');
+    this.manifestPath = join(this.weaveHome, '.joinweave-install.json');
+    this.lockPath = join(this.weaveHome, '.joinweave-install.lock');
+    this.manifest = { schema: 1, installer: 'joinweave', version: VERSION, binary: null, service: null, path: null, mcp: {} };
+    this.warnings = [];
+    this.manualMcp = [];
+  }
+
+  validatePlatform() {
+    if (!['darwin', 'linux'].includes(this.platform)) fail('UNSUPPORTED_PLATFORM', 'joinweave 0.1.0 supports macOS and Linux. Windows service installation is not supported yet.');
+  }
+
+  loadManifest() {
+    const bytes = readFile(this.manifestPath);
+    if (!bytes) return;
+    let value;
+    try { value = JSON.parse(bytes); } catch { fail('INVALID_MANIFEST', 'The installation receipt is invalid. It will not be overwritten.'); }
+    if (!regular(value) || value.schema !== 1 || value.installer !== 'joinweave' || !regular(value.mcp) || (value.binary && !/^[a-f0-9]{64}$/.test(value.binary.sha256))) fail('INVALID_MANIFEST', 'The installation receipt is not recognized. It will not be overwritten.');
+    this.manifest = value;
+  }
+
+  saveManifest() {
+    this.manifest.version = VERSION;
+    atomicWrite(this.manifestPath, Buffer.from(`${JSON.stringify(this.manifest, null, 2)}\n`), { previous: readFile(this.manifestPath) });
+  }
+
+  lock() {
+    assertSafePath(this.lockPath);
+    const old = readFile(this.lockPath);
+    if (old) {
+      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 (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.');
+    }
+    this.lockBytes = Buffer.from(JSON.stringify({ pid: process.pid, host: hostname(), id: randomUUID() }));
+    fs.writeFileSync(this.lockPath, this.lockBytes, { flag: 'wx', mode: 0o600 });
+  }
+
+  unlock() {
+    if (this.lockBytes) 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 (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.`); }
+    if (!regular(data) || data.ok !== true) fail('NATIVE_CHECK_FAILED', `${label} did not report success. Run weave doctor --json or weave node logs to diagnose connectivity.`);
+    return data;
+  }
+
+  async readyDoctor() {
+    const deadline = Date.now() + 30_000;
+    for (let attempt = 0; ; attempt++) {
+      try { return await this.native(['doctor', '--json'], 'Weave doctor', 90_000); }
+      catch (error) {
+        if (!['NATIVE_COMMAND_FAILED', 'NATIVE_CHECK_FAILED'].includes(error.code) || attempt >= 9 || Date.now() >= deadline) throw error;
+        await this.sleep(1_000);
+      }
+    }
+  }
+
+  installBinary() {
+    const source = this.resolveNative();
+    const stat = fs.lstatSync(source);
+    if (!stat.isFile() || stat.isSymbolicLink()) fail('INVALID_BINARY', 'Native package executable must be a regular file.');
+    const bytes = fs.readFileSync(source), sha256 = digest(bytes), old = readFile(this.binary);
+    if (old && (!this.manifest.binary || digest(old) !== this.manifest.binary.sha256)) fail('UNMANAGED_BINARY', `An unrelated or modified executable exists at ${this.binary}. It will not be replaced.`);
+    if (!old || digest(old) !== sha256) atomicWrite(this.binary, bytes, { previous: old, mode: 0o755 });
+    fs.chmodSync(this.binary, 0o755);
+    this.manifest.binary = { sha256, version: VERSION };
+    this.saveManifest();
+    this.progress('Installed Weave');
+  }
+
+  serviceDefinition() {
+    const logs = join(this.weaveHome, 'logs');
+    const environment = { WEAVE_HOME: this.weaveHome };
+    for (const key of ['WEAVE_DHT_BOOTSTRAP', 'WEAVE_DHT_PORT', 'WEAVE_REPLICATION_ADVERTISE_ADDR', 'WEAVE_DHT_DISABLE_QUIC']) {
+      if (this.env[key] === undefined) continue;
+      const value = key === 'WEAVE_DHT_BOOTSTRAP' ? this.env[key].trim().split(/[\s,]+/).join(',') : this.env[key];
+      if (/[\x00-\x1f\x7f]/.test(value)) fail('INVALID_SERVICE_ENV', `${key} cannot contain control characters.`);
+      environment[key] = value;
+    }
+    const logPath = join(logs, 'node.log');
+    if (this.platform === 'darwin') {
+      const entries = Object.entries(environment).map(([key, value]) => `<key>${key}</key><string>${xml(value)}</string>`).join('');
+      return { path: join(this.home, 'Library', 'LaunchAgents', `${serviceName}.plist`), bytes: Buffer.from(`<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n<plist version="1.0"><dict>\n<key>Label</key><string>${serviceName}</string>\n<key>ProgramArguments</key><array><string>${xml(this.binary)}</string><string>node</string><string>run</string></array>\n<key>EnvironmentVariables</key><dict>${entries}</dict>\n<key>WorkingDirectory</key><string>${xml(this.weaveHome)}</string>\n<key>RunAtLoad</key><true/><key>KeepAlive</key><dict><key>SuccessfulExit</key><false/></dict>\n<key>ThrottleInterval</key><integer>5</integer>\n<key>StandardOutPath</key><string>${xml(logPath)}</string>\n<key>StandardErrorPath</key><string>${xml(logPath)}</string>\n</dict></plist>\n`) };
+    }
+    const entries = Object.entries(environment).map(([key, value]) => `Environment=${systemdQuote(`${key}=${value}`)}\n`).join('');
+    return { path: join(this.home, '.config', 'systemd', 'user', 'weave-node.service'), bytes: Buffer.from(`[Unit]\nDescription=Weave peer node\nAfter=network.target\n\n[Service]\nType=simple\nExecStart=${systemdQuote(this.binary, true)} node run\n${entries}WorkingDirectory=${systemdPath(this.weaveHome)}\nRestart=on-failure\nRestartSec=5\nStandardOutput=append:${systemdPath(logPath)}\nStandardError=append:${systemdPath(logPath)}\n\n[Install]\nWantedBy=default.target\n`) };
+  }
+
+  async serviceCommand(args, required = true) {
+    const command = this.platform === 'darwin' ? 'launchctl' : 'systemctl';
+    const result = await this.run(command, args, { env: this.env, timeout: 30_000 });
+    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;
+  }
+
+  async stopService() {
+    if (this.platform === 'darwin') {
+      await this.serviceCommand(['bootout', `gui/${this.uid}/${serviceName}`], false);
+      const status = await this.serviceCommand(['print', `gui/${this.uid}/${serviceName}`], false);
+      if (status.code === 0) fail('SERVICE_STOP_FAILED', 'The launchd node remains registered. Its binary and configuration were preserved.');
+      const missing = `Could not find service "${serviceName}" in domain for user gui: ${this.uid}`;
+      if (status.code !== 113 || !status.stderr.includes(missing)) fail('SERVICE_STOP_UNKNOWN', 'Could not verify launchd shutdown. Its binary and configuration were preserved.');
+    } else {
+      await this.serviceCommand(['--user', 'disable', '--now', 'weave-node.service'], false);
+      const status = await this.serviceCommand(['--user', 'is-active', '--quiet', 'weave-node.service'], false);
+      if (status.code === 0) fail('SERVICE_STOP_FAILED', 'The systemd node remains active. Its binary and configuration were preserved.');
+      if (status.code !== 3 || status.stderr.trim()) fail('SERVICE_STOP_UNKNOWN', 'Could not verify systemd shutdown. Its binary and configuration were preserved.');
+    }
+  }
+
+  async installService() {
+    const service = this.serviceDefinition(), existing = readFile(service.path);
+    if (existing && (!this.manifest.service || this.manifest.service.path !== service.path || digest(existing) !== this.manifest.service.sha256)) fail('UNMANAGED_SERVICE', `An unrelated or modified service exists at ${service.path}. It will not be replaced.`);
+    ensureDirectory(join(this.weaveHome, 'logs'));
+    // Native logs and service log redirections must not follow a pre-existing symlink.
+    const logPath = join(this.weaveHome, 'logs', 'node.log');
+    if (readFile(logPath) === null) fs.writeFileSync(logPath, '', { flag: 'wx', mode: 0o600 });
+    fs.chmodSync(logPath, 0o600);
+    if (existing) await this.stopService();
+    atomicWrite(service.path, service.bytes, { previous: existing, mode: 0o600, backup: Boolean(existing) });
+    this.manifest.service = { platform: this.platform, path: service.path, sha256: digest(service.bytes) };
+    this.saveManifest();
+    if (this.platform === 'darwin') {
+      if (!Number.isInteger(this.uid)) fail('SERVICE_UNAVAILABLE', 'Cannot determine the user launchd session.');
+      await this.serviceCommand(['bootstrap', `gui/${this.uid}`, service.path]);
+    } else {
+      await this.serviceCommand(['--user', 'daemon-reload']);
+      await this.serviceCommand(['--user', 'enable', '--now', 'weave-node.service']);
+    }
+    this.progress('Started the background node');
+  }
+
+  pathDefinition() {
+    const shell = this.env.SHELL || '/bin/sh', name = shell.split('/').pop();
+    if (name === 'fish') return { path: join(this.home, '.config', 'fish', 'config.fish'), block: `${PATH_BEGIN}\nfish_add_path --path --prepend ${shellQuote(dirname(this.binary))}\n${PATH_END}\n` };
+    const path = join(this.home, name === 'zsh' ? '.zshrc' : name === 'bash' ? (this.platform === 'darwin' ? '.bash_profile' : '.bashrc') : '.profile');
+    return { path, block: `${PATH_BEGIN}\nexport PATH=${shellQuote(dirname(this.binary))}:"$PATH"\n${PATH_END}\n` };
+  }
+
+  installPath() {
+    const { path, block } = this.pathDefinition(), old = readFile(path), text = old?.toString('utf8') || '';
+    if (text.includes(PATH_BEGIN) || text.includes(PATH_END)) {
+      if (this.manifest.path?.path === path && this.manifest.path.block === block && text.includes(block)) return;
+      fail('UNMANAGED_PATH_ENTRY', `An unrecognized joinweave PATH block exists in ${path}. It will not be changed.`);
+    }
+    const prefix = text && !text.endsWith('\n') ? '\n' : '';
+    atomicWrite(path, Buffer.from(`${text}${prefix}${block}`), { previous: old, backup: Boolean(old) });
+    this.manifest.path = { path, block };
+    this.saveManifest();
+    this.progress('Added Weave to your shell PATH');
+  }
+
+  clientDefinition(client) {
+    const paths = {
+      'claude-desktop': this.platform === 'darwin' ? join(this.home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json') : join(this.home, '.config', 'Claude', 'claude_desktop_config.json'),
+      'claude-code': join(this.home, '.claude.json'),
+      cursor: join(this.home, '.cursor', 'mcp.json'),
+      codex: join(this.home, '.codex', 'config.toml'),
+    };
+    return { path: paths[client], format: client === 'codex' ? 'toml' : 'json' };
+  }
+
+  detectClients() {
+    const detected = [];
+    const hints = { 'claude-code': join(this.home, '.claude'), cursor: join(this.home, '.cursor'), codex: join(this.home, '.codex') };
+    for (const client of clients) {
+      const { path } = this.clientDefinition(client);
+      // Only test existence here; safety checks happen before a requested edit.
+      if (fs.existsSync(path) || fs.existsSync(hints[client] || dirname(path))) detected.push(client);
+    }
+    for (const client of manualClients) {
+      const appName = client === 'one' ? 'One.app' : 'Bridge.app';
+      if ([join(this.home, `.${client}`), join(this.home, 'Applications', appName), join('/Applications', appName)].some((path) => fs.existsSync(path))) detected.push(client);
+    }
+    return detected;
+  }
+
+  mcpDefinition() {
+    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`;
+  }
+
+  installMcp(client) {
+    if (manualClients.has(client)) {
+      this.manualMcp.push({ client, status: 'manual-setup-required', reason: 'No verified writable MCP configuration schema is available for this client.', server: this.mcpDefinition() });
+      this.progress(`${client} needs manual MCP setup`);
+      return;
+    }
+    const { path, format } = this.clientDefinition(client), old = readFile(path), previous = this.manifest.mcp[client], spec = this.mcpDefinition();
+    let bytes, ownership;
+    if (format === 'json') {
+      let config;
+      try { config = old ? JSON.parse(old.toString('utf8')) : {}; } catch { fail('INVALID_CLIENT_CONFIG', `${client} config is not valid JSON. It will not be changed.`); }
+      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.`);
+      }
+      config.mcpServers.weave = spec;
+      bytes = Buffer.from(`${JSON.stringify(config, null, 2)}\n`);
+      ownership = { path, format, spec };
+    } else {
+      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, '');
+      // 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.');
+      bytes = Buffer.from(`${next}${next && !next.endsWith('\n') ? '\n' : ''}\n${block}`);
+      ownership = { path, format, block };
+    }
+    atomicWrite(path, bytes, { previous: old, backup: Boolean(old) });
+    this.manifest.mcp[client] = ownership;
+    this.saveManifest();
+    this.progress(`Connected ${client}`);
+  }
+
+  async install(options) {
+    this.validatePlatform();
+    ensureDirectory(this.weaveHome);
+    this.lock();
+    try {
+      this.loadManifest();
+      this.installBinary();
+      ensureDirectory(this.shared, 0o755);
+      await this.native(['init', '--json'], 'Workspace initialization');
+      this.progress('Created your workspace and identity');
+      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');
+      } 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();
+      }
+      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];
+      if (!options.noMcp && !options.yes && !options.json) {
+        for (const client of detected) if (!selected.includes(client) && await this.confirm(manualClients.has(client) ? `Show manual Weave MCP setup for ${client}?` : `Add the Weave MCP server to ${client}?`)) selected.push(client);
+      }
+      for (const client of selected) this.installMcp(client);
+      // Doctor owns connectivity, peer and announce/find validation. Never turn a failed doctor into success.
+      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` };
+    } finally { this.unlock(); }
+  }
+
+  async removeService() {
+    const receipt = this.manifest.service;
+    if (!receipt) return;
+    const expected = this.serviceDefinition().path;
+    if (receipt.path !== expected || receipt.platform !== this.platform || !/^[a-f0-9]{64}$/.test(receipt.sha256 || '')) fail('INVALID_MANIFEST', 'Service receipt is not valid for this user and platform.');
+    const bytes = readFile(expected);
+    if (bytes && digest(bytes) !== receipt.sha256) { this.warnings.push('Preserved modified service configuration.'); return; }
+    await this.stopService();
+    unlinkIfUnchanged(expected, receipt.sha256);
+    if (this.platform === 'linux') await this.serviceCommand(['--user', 'daemon-reload'], false);
+    this.manifest.service = null;
+    this.saveManifest();
+  }
+
+  removePath() {
+    const receipt = this.manifest.path;
+    if (!receipt) return;
+    const allowed = [join(this.home, '.zshrc'), join(this.home, '.bashrc'), join(this.home, '.bash_profile'), join(this.home, '.profile'), join(this.home, '.config', 'fish', 'config.fish')];
+    const expectedBlock = receipt.path === allowed.at(-1) ? `${PATH_BEGIN}\nfish_add_path --path --prepend ${shellQuote(dirname(this.binary))}\n${PATH_END}\n` : `${PATH_BEGIN}\nexport PATH=${shellQuote(dirname(this.binary))}:"$PATH"\n${PATH_END}\n`;
+    if (!allowed.includes(receipt.path) || receipt.block !== expectedBlock) fail('INVALID_MANIFEST', 'PATH receipt is not valid.');
+    const old = readFile(receipt.path);
+    if (old) {
+      const text = old.toString('utf8');
+      if (!text.includes(receipt.block)) { this.warnings.push('Preserved modified shell PATH entry.'); return; }
+      atomicWrite(receipt.path, Buffer.from(text.replace(receipt.block, '')), { previous: old, backup: true });
+    }
+    this.manifest.path = null;
+    this.saveManifest();
+  }
+
+  removeMcp(client) {
+    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.');
+    const old = readFile(expected.path);
+    if (old) {
+      let bytes;
+      if (expected.format === 'json') {
+        let config;
+        try { config = JSON.parse(old.toString('utf8')); } catch { this.warnings.push(`Preserved invalid ${client} config.`); return; }
+        if (!regular(config) || !regular(config.mcpServers)) { this.warnings.push(`Preserved modified ${client} config.`); return; }
+        if (Object.hasOwn(config.mcpServers, 'weave')) {
+          if (JSON.stringify(config.mcpServers.weave) !== JSON.stringify(receipt.spec)) { this.warnings.push(`Preserved modified ${client} weave MCP entry.`); return; }
+          delete config.mcpServers.weave;
+          bytes = Buffer.from(`${JSON.stringify(config, null, 2)}\n`);
+        }
+      } 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 (!text.includes(receipt.block)) { this.warnings.push('Preserved modified Codex weave MCP entry.'); return; }
+        bytes = Buffer.from(text.replace(receipt.block, ''));
+      }
+      if (bytes) atomicWrite(expected.path, bytes, { previous: old, backup: true });
+    }
+    delete this.manifest.mcp[client];
+    this.saveManifest();
+  }
+
+  async uninstall(options) {
+    this.validatePlatform();
+    assertSafePath(this.weaveHome);
+    if (!fs.existsSync(this.weaveHome)) return { ok: true, action: 'uninstall', dataRetained: true, warnings: [] };
+    this.lock();
+    let purgeAfterUnlock = false;
+    try {
+      this.loadManifest();
+      const known = readFile(this.manifestPath);
+      if (!known) fail('NO_INSTALL_RECEIPT', 'No joinweave installation receipt exists. Existing files will not be removed.');
+      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);
+      if (binary && this.manifest.binary && digest(binary) === this.manifest.binary.sha256) {
+        await this.native(['node', 'stop', '--json'], 'Node shutdown');
+        unlinkIfUnchanged(this.binary, this.manifest.binary.sha256);
+        this.manifest.binary = null;
+        this.saveManifest();
+      } 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);
+      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);
+        if (receipt) unlinkIfUnchanged(this.manifestPath, digest(receipt));
+      }
+      purgeAfterUnlock = options.purge;
+      return { ok: this.warnings.length === 0, action: 'uninstall', dataRetained: !options.purge, workspace: this.weaveHome, shared: this.shared, warnings: this.warnings };
+    } finally {
+      this.unlock();
+      if (purgeAfterUnlock) {
+        assertSafePath(this.weaveHome);
+        fs.rmSync(this.weaveHome, { recursive: true });
+        // ~/Weave can contain unrelated user files, so even --purge preserves this visible folder.
+      }
+    }
+  }
+}