@digitalygo/spynel 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 frdel
+
+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

@@ -0,0 +1,118 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/digitalygo/spynel/v1.0.0/.github/resources/banner.webp" alt="Spynel — Simplicity. Leverage. Quality." width="100%">
+</p>
+
+<p align="center">
+  <a href="https://agent-zero.ai"><img alt="Website" src="https://img.shields.io/badge/www-agent--zero.ai-0A192F?style=flat&amp;logo=googlechrome&amp;logoColor=white"></a>
+  &nbsp;
+  <a href="https://discord.gg/B8KZKNsPpj"><img alt="Discord" src="https://img.shields.io/badge/Discord-5865F2?style=flat&amp;logo=discord&amp;logoColor=white"></a>
+  &nbsp;
+  <a href="https://x.com/Agent0ai"><img alt="X" src="https://img.shields.io/badge/X-000000?style=flat&amp;logo=x&amp;logoColor=white"></a>
+  &nbsp;
+  <a href="https://www.youtube.com/@AgentZeroFW"><img alt="YouTube" src="https://img.shields.io/badge/YouTube-FF0000?style=flat&amp;logo=youtube&amp;logoColor=white"></a>
+  &nbsp;
+  <a href="https://github.com/sponsors/agent0ai"><img alt="GitHub Sponsors" src="https://img.shields.io/badge/Sponsors-FF69B4?style=flat&amp;logo=githubsponsors&amp;logoColor=white"></a>
+</p>
+
+  <em>Using more agents should not mean spending more time managing agents - that's not leverage.<br> I want to have one communication channel to all my work. One assistant to talk to. One that will do all the management and scaling instead of me.</em>
+  <br><em>Jan Tomášek, founder of <a href="https://github.com/agent0ai/agent-zero">Agent Zero</a></em>
+
+<table>
+  <tr>
+    <td width="50%" valign="middle">
+      <h2>One Human, one Chat</h2>
+      <p>Talk with one assistant for all of your AI automation. No more switching between chats, projects, and spaces - that is work for agents.</p>
+    </td>
+    <td width="50%" align="center">
+      <img src="https://raw.githubusercontent.com/digitalygo/spynel/v1.0.0/.github/resources/readme-one-human-one-chat.webp" alt="One person using a phone connected to one assistant" width="200" style="width: 100%; max-width: 200px; height: auto;">
+    </td>
+  </tr>
+  <tr>
+    <td width="50%" align="center">
+      <img src="https://raw.githubusercontent.com/digitalygo/spynel/v1.0.0/.github/resources/readme-infinite-leverage.webp" alt="One assistant coordinating a network of agents" width="200" style="width: 100%; max-width: 200px; height: auto;">
+    </td>
+    <td width="50%" valign="middle">
+      <h2>Infinite Leverage</h2>
+      <p>Hand off projects, tasks, and agent coordination through the assistant you already talk to. It can orchestrate many independent agents on your behalf, so your leverage scales without your coordination overhead.</p>
+    </td>
+  </tr>
+  <tr>
+    <td width="50%" valign="middle">
+      <h2>Quality Loops</h2>
+      <p>Reliable task management and autonomous agentic loops make thorough testing and review part of the workflow—not an afterthought.</p>
+    </td>
+    <td width="50%" align="center">
+      <img src="https://raw.githubusercontent.com/digitalygo/spynel/v1.0.0/.github/resources/readme-quality.webp" alt="An assistant coordinating task management, testing, and review" width="200" style="width: 100%; max-width: 200px; height: auto;">
+    </td>
+  </tr>
+</table>
+
+
+
+<br><br>
+
+---
+
+# ◉◉ Spynel in a nutshell
+
+- Spynel is a lightweight program with no AI inside.
+- Spynel uses your existing Codex, Claude Code and other coding harnesses to do the work for it.
+- Spynel provides communication interface for you and orchestration framework for agents. 
+
+
+The idea is **one human → one assistant → ALL of the work**
+
+Spynel has three pillars:
+
+1. **Communication interface** — work through a single terminal chat UI, Telegram or WhatsApp
+2. **Markdown task management** — keep tasks, goals, decisions, evidence, and status durable and easily inspectable by any AI harness
+3. **Agentic loops** — let agents plan, implement, review, recover, and ask for human judgment when it matters
+
+**Simplicity. Leverage. Quality.**
+
+## Quick start
+
+For macOS and Linux:
+
+```sh
+curl -LsSf https://raw.githubusercontent.com/digitalygo/spynel/main/install.sh | sh
+spynel
+```
+
+Or use npm (Node.js 18+):
+
+```bash
+npm install -g @digitalygo/spynel
+spynel
+```
+
+Use `spynel update` to update Spynel and restart its running instances. Use `spynel killall` to stop all running Spynel instances.
+
+Run `spynel` from your project directory.
+
+Use `/config` for setup.
+
+
+## Documentation
+
+- **Start here:** [Getting started and development](https://github.com/digitalygo/spynel/blob/v1.0.0/docs/getting-started.md)
+- **Configure Spynel:** [Configuration](https://github.com/digitalygo/spynel/blob/v1.0.0/docs/configuration.md)
+- **Use the TUI, Telegram, WhatsApp, and voice:** [Communication integrations](https://github.com/digitalygo/spynel/blob/v1.0.0/docs/integrations.md)
+- **Choose a coding harness:** [Harness compatibility](https://github.com/digitalygo/spynel/blob/v1.0.0/docs/harness-compatibility.md)
+- **Coordinate durable work:** [Tasks and goals](https://github.com/digitalygo/spynel/blob/v1.0.0/docs/tasks-and-goals.md)
+- **Understand the system and its security boundaries:** [Architecture](https://github.com/digitalygo/spynel/blob/v1.0.0/docs/architecture.md) and [provider-canary threat model](https://github.com/digitalygo/spynel/blob/v1.0.0/docs/provider-canary-threat-model.md)
+- **Automate from the terminal:** [CLI and automation](https://github.com/digitalygo/spynel/blob/v1.0.0/docs/cli.md) and [agent-readable docs](https://github.com/digitalygo/spynel/blob/v1.0.0/docs/agent-docs.md)
+- **Install trusted hooks:** [Extensions](https://github.com/digitalygo/spynel/blob/v1.0.0/docs/extensions.md)
+- **Build and publish releases:** [Releasing and packaging](https://github.com/digitalygo/spynel/blob/v1.0.0/docs/releasing.md)
+- **Diagnose common setup problems:** [Troubleshooting](https://github.com/digitalygo/spynel/blob/v1.0.0/docs/troubleshooting.md)
+- **Read the product principles:** [Product vision](https://github.com/digitalygo/spynel/blob/v1.0.0/docs/vision.md)
+
+See the [documentation index](https://github.com/digitalygo/spynel/blob/v1.0.0/docs/README.md) for the complete guide map.
+
+## Uninstall
+
+```sh
+curl -LsSf https://raw.githubusercontent.com/digitalygo/spynel/main/uninstall.sh | sh
+```
+
+Your workspace data is kept.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,20 @@
+# Third-party notices
+
+Spynel includes open-source Go modules recorded exactly in `go.mod` and `go.sum`. Their source and license files are available from the module repositories identified by `go list -m all`.
+
+Notable runtime components include:
+
+- [sherpa-onnx](https://github.com/k2-fsa/sherpa-onnx) and its official Go bindings, Apache License 2.0. Release archives include its native C API runtime.
+- [ONNX Runtime](https://github.com/microsoft/onnxruntime), MIT License, distributed as part of the sherpa-onnx native runtime.
+- [miniaudio 0.11.25](https://github.com/mackron/miniaudio), MIT No Attribution. Spynel includes the unmodified upstream header and a narrow local decoding adapter.
+- [Pion Opus](https://github.com/pion/opus), MIT License. Spynel uses its pure-Go RFC 6716 decoder for Ogg/Opus voice messages; the full license is included in release archives.
+- [NVIDIA Parakeet Unified EN 0.6B](https://huggingface.co/nvidia/parakeet-unified-en-0.6b), governed by the NVIDIA Open Model License Agreement. Spynel downloads the k2-fsa INT8 ONNX conversion on demand rather than redistributing the weights.
+- [NVIDIA Parakeet TDT 0.6B v3](https://huggingface.co/nvidia/parakeet-tdt-0.6b-v3), © NVIDIA Corporation and licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). Spynel downloads k2-fsa's converted and INT8-quantized ONNX form on demand; those format and quantization changes are not made by Spynel.
+- [whatsmeow](https://github.com/tulir/whatsmeow), Mozilla Public License 2.0. Spynel uses the unmodified upstream module to implement WhatsApp multi-device support. The corresponding source is available from that repository and the exact pseudo-version is recorded in `go.mod`.
+- Bubble Tea, Bubbles, and Lip Gloss, MIT License. Bubble Tea v1.3.10 is retained under `third_party/bubbletea` with its full LICENSE and narrowly documented terminal restoration and key-decoding changes. Release archives include the licenses for that package and the local Bubbles textarea derivative.
+- ncruces/go-sqlite3, MIT License.
+- qrterminal, MIT License.
+- google.golang.org/protobuf, BSD 3-Clause License.
+- gopkg.in/yaml.v3, Apache License 2.0 and MIT License.
+
+All third-party components remain subject to their respective copyright and license terms. This notice does not replace those licenses.

package/npm/bin/AGENTS.md

@@ -0,0 +1,21 @@
+# npm Executable Shim DOX
+
+## Purpose
+
+- Own the installed `spynel` Node executable shim.
+
+## Local Contracts
+
+- Resolve the platform package through the npm wrapper modules, forward arguments and signals to the native executable, and preserve native process exit behavior.
+- Keep native execution asynchronous so SIGINT, SIGTERM and SIGHUP sent to the launcher PID reach its child. Wait for native exit/cleanup before returning or replacing the package; remove forwarding listeners between launches.
+- Validate platform support before update checks or native launch so the Windows stub fails immediately and never searches for a dormant executable.
+- Interactive TUI launches may perform the bounded update flow; noninteractive commands and generated automatic-startup services must not.
+- Keep this file dependency-light and compatible with the Node version declared by the root package manifest.
+
+- Use native check/restart coordination for both startup-offer and explicit-update paths, with bounded subprocess execution. Preserve normalized requester arguments and propagate coordination failures; never report success merely because npm exited successfully.
+
+- The current npm wrapper explicitly advertises coordinated-update support. Bind that capability to validated launcher ownership and include it in process registration; an older wrapper supervising a newer native executable must fail preflight with one-time stop/relaunch guidance instead of silently using the old single-process update protocol.
+
+## Child DOX Index
+
+No child DOX files.

package/npm/bin/spynel.js

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+"use strict";
+
+const path = require("path");
+const os = require("os");
+const crypto = require("crypto");
+const fs = require("fs");
+const childProcess = require("child_process");
+const {
+  checkForUpdate,
+  promptForStartupUpdate,
+  runNPMUpdate,
+  shouldCheckAtStartup
+} = require("../update");
+const { current } = require("../platform");
+
+const UPDATE_EXIT_CODE = 75;
+const packageRoot = path.resolve(__dirname, "..", "..");
+let args = process.argv.slice(2);
+let startupUpdate;
+let startupUpdateCheckedAt;
+
+function createLaunchEnvironment(parentEnvironment = process.env, periodicChecks, checkedAt, update) {
+  const environment = {
+    ...parentEnvironment,
+    SPYNEL_NPM_PACKAGE_ROOT: packageRoot,
+    SPYNEL_NPM_LAUNCHER_MANAGED: "1",
+    SPYNEL_NPM_COORDINATED_UPDATES: "1",
+    SPYNEL_NPM_LAUNCHER: __filename,
+    SPYNEL_NPM_NODE: process.execPath,
+    SPYNEL_NPM_UPDATE_STATE: path.join(os.tmpdir(), `spynel-update-${process.pid}-${crypto.randomBytes(8).toString("hex")}.json`)
+  };
+  delete environment.SPYNEL_NPM_PERIODIC_UPDATE_CHECKS;
+  delete environment.SPYNEL_NPM_UPDATE_CHECKED_AT;
+  delete environment.SPYNEL_NPM_UPDATE_LATEST;
+  if (periodicChecks) environment.SPYNEL_NPM_PERIODIC_UPDATE_CHECKS = "1";
+  if (checkedAt) environment.SPYNEL_NPM_UPDATE_CHECKED_AT = checkedAt;
+  if (update) environment.SPYNEL_NPM_UPDATE_LATEST = update.latest;
+  return environment;
+}
+
+function coordinateInstances(command, environment) {
+  const result = childProcess.spawnSync(path.join(packageRoot, "npm", "vendor", "spynel"), [command], {
+    stdio: ["ignore", "ignore", "inherit"], env: environment, timeout: 40_000
+  });
+  if (result.error || result.status !== 0) {
+    throw result.error || new Error("Spynel instance coordination failed; review the error above");
+  }
+}
+
+async function main() {
+  current();
+  const periodicChecks = shouldCheckAtStartup(args);
+  if (periodicChecks) {
+    startupUpdateCheckedAt = new Date().toISOString();
+    try {
+      const update = await checkForUpdate();
+      startupUpdate = update;
+      if (update.available && await promptForStartupUpdate(update, { packageRoot })) {
+        try {
+          const environment = createLaunchEnvironment(process.env, false);
+          coordinateInstances("check-restartable", environment);
+          runNPMUpdate({ packageRoot, expectedVersion: update.latest });
+          coordinateInstances("restart-instances", environment);
+        } catch (error) {
+          console.error(`Unable to update Spynel: ${error.message}. Starting the installed version.`);
+        }
+      }
+    } catch (error) {
+      // Startup must remain available when npm or the network is slow. The
+      // explicit /update command reports errors in chat when the user asks.
+      if (process.env.SPYNEL_DEBUG_UPDATE === "1") {
+        console.warn(`Spynel update check skipped: ${error.message}`);
+      }
+    }
+  }
+
+  const environment = createLaunchEnvironment(process.env, periodicChecks, startupUpdateCheckedAt, startupUpdate);
+  for (;;) {
+    const binary = path.join(__dirname, "..", "vendor", "spynel");
+    const result = await new Promise(resolve => {
+      const child = childProcess.spawn(binary, args, { stdio: "inherit", env: environment });
+      const signals = ["SIGINT", "SIGTERM", "SIGHUP"].map(signal => [signal, () => child.kill(signal)]);
+      const finish = result => {
+        for (const [signal, forward] of signals) process.removeListener(signal, forward);
+        resolve(result);
+      };
+      for (const [signal, forward] of signals) process.on(signal, forward);
+      child.once("error", error => finish({ error }));
+      child.once("close", (status, signal) => finish({ status, signal }));
+    });
+    if (result.error) {
+      fs.rmSync(environment.SPYNEL_NPM_UPDATE_STATE, { force: true });
+      console.error(`Unable to run Spynel: ${result.error.message}`);
+      return 1;
+    }
+    if (result.status !== UPDATE_EXIT_CODE) {
+      fs.rmSync(environment.SPYNEL_NPM_UPDATE_STATE, { force: true });
+      return result.status === null ? 1 : result.status;
+    }
+    let request = {};
+    try {
+      request = JSON.parse(fs.readFileSync(environment.SPYNEL_NPM_UPDATE_STATE, "utf8"));
+      if (Array.isArray(request.args)) args = request.args;
+    } catch (_) {
+      // Older binaries do not publish restart arguments; reuse this launch.
+    }
+    fs.rmSync(environment.SPYNEL_NPM_UPDATE_STATE, { force: true });
+    try {
+      coordinateInstances("check-restartable", environment);
+      if (request.install !== false) runNPMUpdate({ packageRoot, expectedVersion: request.version });
+      coordinateInstances("restart-instances", environment);
+    } catch (error) {
+      console.error(`Unable to update Spynel: ${error.message}`);
+      if (args.length === 0 || args[0] === "serve") continue;
+      return 1;
+    }
+  }
+}
+
+if (require.main === module) {
+  main().then(code => process.exit(code), error => {
+    console.error(`Unable to run Spynel: ${error.message}`);
+    process.exit(1);
+  });
+}
+
+module.exports = { createLaunchEnvironment };

package/npm/install.js

@@ -0,0 +1,182 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const https = require("https");
+const http = require("http");
+const childProcess = require("child_process");
+const crypto = require("crypto");
+const { current } = require("./platform");
+const pkg = require("../package.json");
+
+const version = pkg.version;
+const vendor = path.join(__dirname, "vendor");
+const marker = path.join(vendor, ".installed.json");
+const MAX_ARCHIVE_BYTES = 512 * 1024 * 1024;
+const MAX_CHECKSUM_BYTES = 1024 * 1024;
+const MAX_ARCHIVE_ENTRIES = 4096;
+const MAX_ENTRY_PATH_BYTES = 1024;
+const MAX_EXPANDED_BYTES = 2 * 1024 * 1024 * 1024;
+
+function download(url, file, maxBytes, redirects = 0, secureRequired = new URL(url).protocol === "https:") {
+  return new Promise((resolve, reject) => {
+    const parsed = new URL(url);
+    if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+      return reject(new Error(`unsupported download protocol: ${parsed.protocol}`));
+    }
+    if (secureRequired && parsed.protocol !== "https:") {
+      return reject(new Error("release download refused an HTTPS-to-HTTP redirect"));
+    }
+    const transport = parsed.protocol === "https:" ? https : http;
+    const request = transport.get(parsed, response => {
+      if (response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
+        response.resume();
+        if (redirects >= 5) return reject(new Error("too many redirects"));
+        return resolve(download(new URL(response.headers.location, parsed).toString(), file, maxBytes, redirects + 1, secureRequired));
+      }
+      if (response.statusCode !== 200) {
+        response.resume();
+        return reject(new Error(`download failed (${response.statusCode})`));
+      }
+      const declared = Number(response.headers["content-length"]);
+      if (Number.isFinite(declared) && declared > maxBytes) {
+        response.resume();
+        return reject(new Error(`release download exceeds the ${maxBytes} byte limit`));
+      }
+      let received = 0;
+      const output = fs.createWriteStream(file, { flags: "wx", mode: 0o600 });
+      response.on("data", chunk => {
+        received += chunk.length;
+        if (received > maxBytes) request.destroy(new Error(`release download exceeds the ${maxBytes} byte limit`));
+      });
+      response.pipe(output);
+      output.on("finish", () => output.close(resolve));
+      output.on("error", reject);
+      response.on("error", reject);
+    });
+    request.setTimeout(120_000, function () {
+      this.destroy(new Error("release download timed out"));
+    });
+    request.on("error", reject);
+  });
+}
+
+function sha256File(file) {
+  return new Promise((resolve, reject) => {
+    const hash = crypto.createHash("sha256");
+    const input = fs.createReadStream(file);
+    input.on("data", chunk => hash.update(chunk));
+    input.on("end", () => resolve(hash.digest("hex")));
+    input.on("error", reject);
+  });
+}
+
+function validateArchiveEntries(entries) {
+  if (!Array.isArray(entries) || entries.length === 0) throw new Error("release archive is empty");
+  if (entries.length > MAX_ARCHIVE_ENTRIES) throw new Error("release archive contains too many entries");
+  for (const original of entries) {
+    if (typeof original !== "string" || Buffer.byteLength(original) > MAX_ENTRY_PATH_BYTES) {
+      throw new Error("release archive contains an invalid entry path");
+    }
+    if (/[\0-\x1f\x7f]/.test(original)) throw new Error("release archive entry contains control characters");
+    const entry = original.replaceAll("\\", "/").replace(/\/+$/, "");
+    if (entry === "" || entry === ".") continue;
+    if (entry.startsWith("/") || entry.startsWith("//") || /^[A-Za-z]:/.test(entry)) {
+      throw new Error(`release archive contains an absolute path: ${original}`);
+    }
+    if (entry.split("/").some(segment => segment === "..")) {
+      throw new Error(`release archive escapes its staging directory: ${original}`);
+    }
+  }
+}
+
+function listArchiveEntries(file) {
+  const output = childProcess.execFileSync("tar", ["-tzf", file], { encoding: "utf8", maxBuffer: 4 * 1024 * 1024 });
+  const entries = output.split(/\r?\n/).filter(Boolean);
+  validateArchiveEntries(entries);
+  return entries;
+}
+
+function validateExtractedTree(root) {
+  let entries = 0;
+  let bytes = 0;
+  const visit = directory => {
+    for (const name of fs.readdirSync(directory)) {
+      entries += 1;
+      if (entries > MAX_ARCHIVE_ENTRIES) throw new Error("release archive contains too many extracted entries");
+      const item = path.join(directory, name);
+      const info = fs.lstatSync(item);
+      if (info.isSymbolicLink()) throw new Error(`release archive contains a symbolic link: ${name}`);
+      if (info.isDirectory()) {
+        visit(item);
+      } else if (info.isFile()) {
+        bytes += info.size;
+        if (bytes > MAX_EXPANDED_BYTES) throw new Error("release archive expands beyond its byte limit");
+      } else {
+        throw new Error(`release archive contains an unsupported entry: ${name}`);
+      }
+    }
+  };
+  visit(root);
+}
+
+async function install() {
+  const target = current();
+  const archive = `spynel_${version}_${target.os}_${target.arch}.${target.ext}`;
+  const base = process.env.SPYNEL_DOWNLOAD_BASE || `https://github.com/digitalygo/spynel/releases/download/v${version}`;
+  const destination = path.join(vendor, "spynel");
+  if (fs.existsSync(destination) && fs.existsSync(marker)) {
+    try {
+      const installed = JSON.parse(fs.readFileSync(marker, "utf8"));
+      if (installed.version === version && installed.os === target.os && installed.arch === target.arch) return;
+    } catch (_) {}
+  }
+  const staging = fs.mkdtempSync(path.join(__dirname, ".install-"));
+  try {
+    const temp = path.join(staging, archive);
+    await download(`${base}/${archive}`, temp, MAX_ARCHIVE_BYTES);
+    const checksums = path.join(staging, "checksums.txt");
+    await download(`${base}/checksums.txt`, checksums, MAX_CHECKSUM_BYTES);
+    const expectedLine = fs.readFileSync(checksums, "utf8").split(/\r?\n/).find(line => line.trim().endsWith(`  ${archive}`));
+    if (!expectedLine) throw new Error(`release checksum is missing for ${archive}`);
+    const expected = expectedLine.trim().split(/\s+/)[0].toLowerCase();
+    if (!/^[a-f0-9]{64}$/.test(expected)) throw new Error(`release checksum is invalid for ${archive}`);
+    const actual = await sha256File(temp);
+    if (actual !== expected) throw new Error(`checksum mismatch for ${archive}`);
+    fs.rmSync(checksums);
+    listArchiveEntries(temp);
+    childProcess.execFileSync("tar", ["-xzf", temp, "-C", staging, "--no-same-owner", "--no-same-permissions"]);
+    fs.rmSync(temp);
+    validateExtractedTree(staging);
+    const stagedBinary = path.join(staging, "spynel");
+    if (!fs.lstatSync(stagedBinary).isFile()) throw new Error(`release archive does not contain ${path.basename(stagedBinary)}`);
+    fs.chmodSync(stagedBinary, 0o755);
+    fs.writeFileSync(path.join(staging, ".installed.json"), JSON.stringify({ version, os: target.os, arch: target.arch }) + "\n", { mode: 0o600 });
+    const backup = path.join(__dirname, `.vendor-backup-${process.pid}`);
+    fs.rmSync(backup, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+    if (fs.existsSync(vendor)) fs.renameSync(vendor, backup);
+    try {
+      fs.renameSync(staging, vendor);
+    } catch (error) {
+      if (fs.existsSync(backup)) fs.renameSync(backup, vendor);
+      throw error;
+    }
+    try {
+      fs.rmSync(backup, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+    } catch (error) {
+      console.warn(`Spynel was installed but its previous vendor backup could not be removed: ${error.message}`);
+    }
+  } catch (error) {
+    fs.rmSync(staging, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+if (require.main === module) {
+  install().catch(error => {
+    console.error(`Unable to install Spynel: ${error.message}`);
+    process.exitCode = 1;
+  });
+}
+
+module.exports = { install, validateArchiveEntries, validateExtractedTree };

package/npm/platform.js

@@ -0,0 +1,24 @@
+"use strict";
+
+const mapping = {
+  "linux-x64": ["linux", "amd64", "tar.gz"],
+  "linux-arm64": ["linux", "arm64", "tar.gz"],
+  "darwin-x64": ["darwin", "amd64", "tar.gz"],
+  "darwin-arm64": ["darwin", "arm64", "tar.gz"]
+};
+
+function resolve(platform, arch) {
+  const key = `${platform}-${arch}`;
+  if (platform === "win32") {
+    throw new Error("Spynel does not currently support Windows; use Linux or macOS");
+  }
+  const target = mapping[key];
+  if (!target) throw new Error(`Spynel does not publish a binary for ${key}`);
+  return { os: target[0], arch: target[1], ext: target[2] };
+}
+
+function current() {
+  return resolve(process.platform, process.arch);
+}
+
+module.exports = { current, resolve };

package/npm/update.js

@@ -0,0 +1,246 @@
+"use strict";
+
+const childProcess = require("child_process");
+const fs = require("fs");
+const http = require("http");
+const https = require("https");
+const path = require("path");
+const readline = require("readline");
+const pkg = require("../package.json");
+
+const DEFAULT_TIMEOUT_MS = 10_000;
+const STARTUP_PROMPT_TIMEOUT_MS = 10_000;
+const DEFAULT_REGISTRY_URL = "https://registry.npmjs.org/@digitalygo%2Fspynel/latest";
+const MAX_RESPONSE_BYTES = 64 * 1024;
+
+function parseVersion(value) {
+  const match = String(value).trim().replace(/^v/, "").match(/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/);
+  if (!match) return null;
+  return {
+    numbers: [Number(match[1]), Number(match[2]), Number(match[3])],
+    prerelease: match[4] ? match[4].split(".") : []
+  };
+}
+
+function compareVersions(left, right) {
+  const a = parseVersion(left);
+  const b = parseVersion(right);
+  if (!a || !b) throw new Error(`invalid semantic version: ${!a ? left : right}`);
+  for (let index = 0; index < 3; index += 1) {
+    if (a.numbers[index] !== b.numbers[index]) return a.numbers[index] < b.numbers[index] ? -1 : 1;
+  }
+  if (a.prerelease.length === 0 || b.prerelease.length === 0) {
+    if (a.prerelease.length === b.prerelease.length) return 0;
+    return a.prerelease.length === 0 ? 1 : -1;
+  }
+  const limit = Math.min(a.prerelease.length, b.prerelease.length);
+  for (let index = 0; index < limit; index += 1) {
+    const aValue = a.prerelease[index];
+    const bValue = b.prerelease[index];
+    if (aValue === bValue) continue;
+    const aNumeric = /^(0|[1-9]\d*)$/.test(aValue);
+    const bNumeric = /^(0|[1-9]\d*)$/.test(bValue);
+    if (aNumeric && bNumeric) return Number(aValue) < Number(bValue) ? -1 : 1;
+    if (aNumeric !== bNumeric) return aNumeric ? -1 : 1;
+    return aValue < bValue ? -1 : 1;
+  }
+  if (a.prerelease.length === b.prerelease.length) return 0;
+  return a.prerelease.length < b.prerelease.length ? -1 : 1;
+}
+
+function requestJSON(url, timeoutMs, redirects = 0, deadline = Date.now() + timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const parsed = new URL(url);
+    const transport = parsed.protocol === "https:" ? https : http;
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) return reject(new Error(`npm update check timed out after ${timeoutMs}ms`));
+    const request = transport.get(parsed, {
+      headers: {
+        Accept: "application/json",
+        "User-Agent": `spynel/${pkg.version}`
+      }
+    }, response => {
+      if (response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
+        response.resume();
+        if (redirects >= 5) {
+          clearTimeout(timer);
+          return reject(new Error("npm registry returned too many redirects"));
+        }
+        clearTimeout(timer);
+        return resolve(requestJSON(new URL(response.headers.location, parsed).toString(), timeoutMs, redirects + 1, deadline));
+      }
+      if (response.statusCode !== 200) {
+        response.resume();
+        clearTimeout(timer);
+        return reject(new Error(`npm registry returned ${response.statusCode}`));
+      }
+      const chunks = [];
+      let size = 0;
+      response.on("data", chunk => {
+        size += chunk.length;
+        if (size > MAX_RESPONSE_BYTES) {
+          request.destroy(new Error("npm registry response is too large"));
+          return;
+        }
+        chunks.push(chunk);
+      });
+      response.on("end", () => {
+        clearTimeout(timer);
+        try {
+          resolve(JSON.parse(Buffer.concat(chunks).toString("utf8")));
+        } catch (error) {
+          reject(new Error(`invalid npm registry response: ${error.message}`));
+        }
+      });
+    });
+    const timer = setTimeout(() => request.destroy(new Error(`npm update check timed out after ${timeoutMs}ms`)), remaining);
+    request.on("error", error => {
+      clearTimeout(timer);
+      reject(error);
+    });
+  });
+}
+
+async function checkForUpdate(options = {}) {
+  const current = options.current || pkg.version;
+  const registryURL = options.registryURL || process.env.SPYNEL_NPM_REGISTRY_URL || DEFAULT_REGISTRY_URL;
+  const timeoutMs = options.timeoutMs || DEFAULT_TIMEOUT_MS;
+  const metadata = await requestJSON(registryURL, timeoutMs);
+  if (!metadata || typeof metadata.version !== "string" || !parseVersion(metadata.version)) {
+    throw new Error("npm registry did not return a semantic Spynel version");
+  }
+  return {
+    current,
+    latest: metadata.version,
+    available: compareVersions(metadata.version, current) > 0
+  };
+}
+
+function shouldCheckAtStartup(args, input = process.stdin, output = process.stdout, environment = process.env) {
+  const interactiveStart = args.length === 0 || args[0] === "init" || (args[0] === "serve" && args.includes("--tui"));
+  return interactiveStart && !args.includes("--automatic-startup") &&
+    environment.SPYNEL_SKIP_UPDATE_CHECK !== "1" &&
+    Boolean(input.isTTY && output.isTTY);
+}
+
+function samePath(left, right) {
+  try {
+    return fs.realpathSync(left) === fs.realpathSync(right);
+  } catch (_) {
+    return path.resolve(left) === path.resolve(right);
+  }
+}
+
+function npmInvocation(packageRoot = path.resolve(__dirname, "..")) {
+  const npm = process.platform === "win32" ? "npm.cmd" : "npm";
+  const rootResult = childProcess.spawnSync(npm, ["root", "--global"], { encoding: "utf8", windowsHide: true, timeout: DEFAULT_TIMEOUT_MS });
+  const globalRoot = rootResult.status === 0 ? rootResult.stdout.trim() : "";
+  if (globalRoot && samePath(packageRoot, path.join(globalRoot, pkg.name))) {
+    return { command: npm, args: ["update", "--global", pkg.name], display: `npm update --global ${pkg.name}` };
+  }
+  const parent = path.dirname(packageRoot);
+  const nodeModules = path.basename(parent).startsWith("@") ? path.dirname(parent) : parent;
+  const prefix = path.basename(nodeModules) === "node_modules" ? path.dirname(nodeModules) : process.cwd();
+  return { command: npm, args: ["update", pkg.name, "--prefix", prefix], display: `npm update ${pkg.name}` };
+}
+
+function runNPMUpdate(options = {}) {
+  const packageRoot = options.packageRoot || path.resolve(__dirname, "..");
+  const before = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8")).version;
+  const invocation = npmInvocation(packageRoot);
+  const result = childProcess.spawnSync(invocation.command, invocation.args, {
+    cwd: packageRoot,
+    stdio: options.stdio || "inherit",
+    windowsHide: false
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0) throw new Error(`${invocation.display} exited with status ${result.status}`);
+  const after = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8")).version;
+  if (compareVersions(after, before) < 0 || (options.expectedVersion ? compareVersions(after, options.expectedVersion) < 0 : compareVersions(after, before) <= 0)) {
+    throw new Error(`${invocation.display} completed but Spynel remained at ${after}; check the project's dependency range or update it manually`);
+  }
+  return { ...invocation, before, after };
+}
+
+async function promptForStartupUpdate(result, options = {}) {
+  const input = options.input || process.stdin;
+  const output = options.output || process.stdout;
+  if (!input.isTTY || !output.isTTY) return false;
+
+  const invocation = npmInvocation(options.packageRoot);
+  const environment = options.environment || process.env;
+  const timeoutMs = options.timeoutMs || STARTUP_PROMPT_TIMEOUT_MS;
+  const tickMs = options.tickMs || 1_000;
+  const countdownUnitMs = options.countdownUnitMs || 1_000;
+  const styled = environment.NO_COLOR === undefined && environment.TERM !== "dumb";
+  const cursorControl = options.cursorControl !== false && environment.TERM !== "dumb";
+  const bold = value => styled ? `\x1b[1m${value}\x1b[22m` : value;
+  const muted = value => styled ? `\x1b[2m${value}\x1b[22m` : value;
+  const terminal = readline.createInterface({ input, output, terminal: true });
+  const deadline = Date.now() + timeoutMs;
+  let lastRemaining = Math.ceil(timeoutMs / countdownUnitMs);
+  let firstPrompt = true;
+  let settled = false;
+
+  output.write(`\n⬆️  New version ${result.latest} available — current is ${result.current}\n`);
+  const renderPrompt = (remaining, ending = "") => {
+    const suffix = ending || `skipping in ${remaining}…`;
+    const line = `${bold("Update now")}? [Y]es / [N]o  ${muted(suffix)}`;
+    if (cursorControl) {
+      terminal.setPrompt(line);
+      terminal.prompt(!firstPrompt);
+    } else {
+      if (!firstPrompt) output.write("\n");
+      output.write(line);
+    }
+    firstPrompt = false;
+  };
+  renderPrompt(lastRemaining);
+
+  return new Promise(resolve => {
+    let interval;
+    let timeout;
+    const finish = (update, ending) => {
+      if (settled) return;
+      settled = true;
+      clearInterval(interval);
+      clearTimeout(timeout);
+      terminal.close();
+      if (cursorControl) {
+        readline.cursorTo(output, 0);
+        readline.clearLine(output, 0);
+        output.write(`${bold("Update now")}? [Y]es / [N]o  ${muted(ending)}`);
+      } else {
+        renderPrompt(0, ending);
+      }
+      output.write("\n");
+      resolve(update);
+    };
+    terminal.once("line", answer => {
+      const normalized = answer.trim().toLowerCase();
+      finish(normalized === "y" || normalized === "yes", normalized === "y" || normalized === "yes" ? `running ${invocation.display}…` : "skipping.");
+    });
+    terminal.once("SIGINT", () => finish(false, "skipping."));
+    terminal.once("close", () => finish(false, "skipping."));
+    interval = setInterval(() => {
+      const remaining = Math.max(0, Math.ceil((deadline - Date.now()) / countdownUnitMs));
+      if (remaining !== lastRemaining && remaining > 0) {
+        lastRemaining = remaining;
+        renderPrompt(remaining);
+      }
+    }, tickMs);
+    timeout = setTimeout(() => finish(false, "timed out; skipping."), timeoutMs);
+  });
+}
+
+module.exports = {
+  DEFAULT_TIMEOUT_MS,
+  STARTUP_PROMPT_TIMEOUT_MS,
+  checkForUpdate,
+  compareVersions,
+  npmInvocation,
+  parseVersion,
+  promptForStartupUpdate,
+  runNPMUpdate,
+  shouldCheckAtStartup
+};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@digitalygo/spynel",
+  "version": "1.0.0",
+  "description": "A non-AI orchestration layer connecting one human to many coding agents",
+  "license": "MIT",
+  "keywords": [
+    "coding-agent",
+    "multi-agent",
+    "orchestration",
+    "terminal-ui",
+    "telegram",
+    "whatsapp",
+    "automation"
+  ],
+  "bin": {
+    "spynel": "npm/bin/spynel.js"
+  },
+  "scripts": {
+    "postinstall": "node npm/install.js",
+    "test": "node npm/test.js",
+    "test:npm": "node npm/test.js"
+  },
+  "files": [
+    "npm/bin/",
+    "npm/install.js",
+    "npm/platform.js",
+    "npm/update.js",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/digitalygo/spynel.git"
+  },
+  "bugs": {
+    "url": "https://github.com/digitalygo/spynel/issues"
+  },
+  "homepage": "https://github.com/digitalygo/spynel#readme",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  }
+}