kodelyth-ecc 2.24.7 → 2.24.9

package/CHANGELOG.md

@@ -2,6 +2,156 @@
 
 All notable changes to Kodelyth ECC are documented here.
 
+## v2.24.9 — a malformed Claude config was silently replaced on install (October 2026)
+
+**Data-loss fix. Upgrade before running an install on a machine whose
+`~/.claude.json` may have been hand-edited.**
+
+MCP self-registration read the user's Claude config, merged ECC's server entry in,
+and wrote it back:
+
+```js
+const existing = readJson(file) || {};
+const next = { ...existing, mcpServers: servers };
+writeJson(file, next);
+```
+
+`readJson` returned `null` for **every** failure. So a config that merely failed to
+parse — one trailing comma from a hand-edit, a half-written file, a bad mount —
+was indistinguishable from a config that did not exist, and `|| {}` turned it into
+an empty object. The merge then wrote that back.
+
+Measured on a realistic config with two other MCP servers, a `projects` block with
+history, and user settings: **366 bytes in, 140 bytes out**. Every other MCP
+server, every project entry, the theme and `autoUpdates` — gone. No error, no
+warning, no backup.
+
+This runs automatically during install. So `npx kodelyth-ecc` on a machine whose
+`.claude.json` had any syntax error destroyed the user's Claude configuration.
+
+### What changed
+
+`readConfig` now returns one of three states instead of a nullable value:
+
+| state | meaning | action |
+|---|---|---|
+| `absent` | missing, empty, or whitespace-only | safe to treat as `{}` and create |
+| `present` | parsed to an object | merge normally |
+| `unreadable` | exists but will not parse, or is not an object | **refuse** |
+
+Refusing is the point: there is no safe way to merge into a file whose contents
+cannot be reconstructed. The file is left byte-identical and the error names it
+along with the parse failure. `unregisterInFile` applies the same rule on the way
+out — removing an entry from a file we cannot read means writing a file we cannot
+reconstruct.
+
+Writes now go through `safeFs.replaceFilePreservingMode`: atomic via
+temp-and-rename, so a crash or a full disk partway through cannot truncate the
+config — the same data loss by a different route — and the file keeps its existing
+permissions rather than having them widened.
+
+### Two mistakes caught while fixing it
+
+The first version of the fix called `replaceFileAtomic` without its `mode`
+argument, which threw on **every** path including valid configs. Testing the happy
+path, not just the bug, is what surfaced it; verifying only that the refusal
+worked would have shipped an installer that never registered anything.
+
+The mode-preservation test then asserted `mode === 0o600` and failed Windows CI
+with `438 !== 384`. Windows has no POSIX permission bits, so `chmod` there is close
+to a no-op and node reports `0666` regardless. The property worth testing was never
+the literal value but that the write does not *change* the mode, which is true on
+every platform.
+
+Eight tests, where this file previously had none: the three read states,
+preservation of unrelated config on a valid merge, byte-identical refusal across
+four kinds of malformed input, creation from absent and empty, idempotence,
+unregister's refusal, mode preservation, and no stray temp files.
+
+**690 tests across 44 files.**
+
+## v2.24.8 — adversarial pass: swarm, dashboard, supply-chain (October 2026)
+
+Three defects found by attacking the remaining unprobed surfaces rather than
+reading them.
+
+### `baseRef` could reach git's argv as an option
+
+Every spawn in the swarm orchestrator uses `spawnSync`'s array form with no shell,
+so shell injection does not work — and that was tested, not assumed: every
+generated `send-keys` string was executed in a real shell with a payload that
+would touch a marker file, across sessionName, worker name, task, repoRoot and
+baseRef. No marker was ever created.
+
+Array form does not stop **argument** injection, though. git parses its own argv,
+so in `git worktree add -b <branch> <path> <commit-ish>` a commit-ish beginning
+with `-` is read as an option: `--git-dir=/elsewhere` points git at another
+repository, `--force` changes the command's meaning. `baseRef` was the only value
+reaching argv without being slugified or path-resolved first — sessionName goes
+through `slugify`, branchName carries a literal prefix, worktreePath is absolute —
+and it is user-settable through `--base-ref`. Swarm configs get shared, so this is
+not purely self-inflicted.
+
+Rejecting a leading `-` costs nothing: `git check-ref-format` forbids refs that
+start with one, so `HEAD`, `main`, `v1.2.3` and `origin/main` all still work.
+
+### An 800-character excerpt read the entire file
+
+The dashboard's `safeReadExcerpt` called `readFileSync` on the whole file and then
+sliced 800 characters off the front, so a fixed-size excerpt cost the full size of
+the file. Measured on a 300MB `task.md`: **196ms and +628MB RSS** for 800
+characters, scaling linearly — roughly twice the file, since the bytes land in a
+Buffer and again as a UTF-16 string.
+
+The dashboard is single threaded, so that blocks every other request, and it runs
+three times per worker — task, handoff, status — across every session in
+`.orchestration`. Those files are written by swarm workers, so their size is not
+something the dashboard controls.
+
+It now reads a bounded window: stat first, then `max * 4 + 4` bytes. Four because
+UTF-8 encodes a character in at most four, so the window always holds at least
+`max` characters. That detail is load bearing — the truncation decision counts
+CHARACTERS, as it always did, so slicing a byte window would cut a multi-byte
+character in half. 300MB now costs 0ms and +0MB. Output was diffed against the old
+implementation across twelve cases including emoji on the boundary; all identical.
+
+### `verify` passed with a planted file
+
+An EXTRA file — present on disk, absent from the manifest — was advisory:
+`ok: true`, exit code 0. Confirmed against the real CLI, where tampering and
+deletion correctly exit 1 but planting `rules/common/zz-injected.md` exits 0.
+
+The human output did say `⚠ extra: 1 (advisory)`. Automation did not hear it:
+`kodelyth-ecc verify && deploy` passed with an unknown file in place — and in this
+product an extra `.md` under `rules/`, `agents/` or `commands/` is not inert data.
+Those directories are enumerated and loaded as instructions, so an injected rule
+file becomes an always-on rule in every future session. That is the payload the
+session-bundle traversal delivered in 2.24.5, reached a different way.
+
+The default is deliberately unchanged. This is a toolkit people are meant to
+extend, and failing verify on extras would fail it forever for anyone who added
+their own agent — a check that always fails gets ignored. The choice is offered
+instead:
+
+```bash
+kodelyth-ecc verify            # extras advisory, exit 0 (unchanged)
+kodelyth-ecc verify --strict   # extras fail the verdict, exit 1
+```
+
+The report now carries `strict`, so a `--json` consumer need not infer which mode
+produced the verdict.
+
+### What held up
+
+`scripts/evolve` was already hardened, and its comment records the same traversal
+class found in replay along with how it was confirmed. Re-tested anyway: target
+path traversal blocked, legitimate paths written, no prototype pollution. Swarm
+worker names collapse through `slugify` rather than escaping the worktree root,
+and `normalizeSeedPaths` rejects `..`, absolute paths and embedded traversal —
+both now pinned by tests so a later change cannot quietly lose them.
+
+**682 tests across 43 files.**
+
 ## v2.24.7 — the brand render scripts could not run (October 2026)
 
 Developer tooling only. Nothing here ships in the npm package — `brand/` is not in

package/CLAUDE.md

@@ -26,7 +26,7 @@ scripts/     → Node.js utilities: MCP server, dashboard, swarm, replay, router
 bundles/     → 3 power bundles (indie-hacker, red-team, enterprise)
 actions/     → GitHub Action (CI/CD integration for PR review)
 docs/        → Feature docs (arena.md, mcp.md, dashboard.md, swarm.md, replay.md, evolve.md, supply-chain.md)
-tests/       → 672 passing tests across 43 test files
+tests/       → 690 passing tests across 44 test files
 ```
 
 ## Running Tests

package/README.md

@@ -118,7 +118,7 @@ Most "AI agent kits" are folders of markdown files you have to remember the name
 | Quality hooks | ✓ 44 | Some | ✗ | ✗ |
 | IDE platforms | **11** (Claude Code, Windsurf, Cursor, Codex, Antigravity, OpenCode, Cline, Roo Code, Aider, Kimi, Gemini CLI) | 1-2 | 1 | Varies |
 | Telemetry | **None** | Varies | None | Varies |
-| Test coverage | ✓ 672 tests | ✗ | ✗ | ✗ |
+| Test coverage | ✓ 690 tests | ✗ | ✗ | ✗ |
 | Distributed via | `npx`, curl, clone | Manual | Manual | Manual |
 
 ---

package/bin/kodelyth-ecc.js

@@ -1288,7 +1288,7 @@ if (args[0] === 'session-export' || args[0] === 'session-import' || args[0] ===
 // Usage:
 //   kodelyth-ecc sbom        [--root DIR] [--out FILE] [--json]
 //   kodelyth-ecc manifest    [--root DIR] [--out FILE] [--json]
-//   kodelyth-ecc verify      [--root DIR] [--manifest FILE] [--json]
+//   kodelyth-ecc verify      [--root DIR] [--manifest FILE] [--json] [--strict]
 if (args[0] === 'sbom' || args[0] === 'manifest' || args[0] === 'verify') {
   (async () => {
     const fs   = require('fs');
@@ -1355,7 +1355,12 @@ if (args[0] === 'sbom' || args[0] === 'manifest' || args[0] === 'verify') {
           throw new Error(`verify: manifest not found at ${manifestPath} (use --manifest FILE)`);
         }
         const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
-        const report = verifyAgainstManifest({ rootDir, manifest });
+        // --strict folds EXTRA files into the verdict. Off by default, because a
+        // toolkit people extend would otherwise fail verify for everyone who added
+        // their own agent; on for automation, where an unknown file under rules/ or
+        // agents/ is loaded as instructions and should stop a deploy.
+        const strict = has('--strict');
+        const report = verifyAgainstManifest({ rootDir, manifest, strict });
 
         if (has('--json')) {
           process.stdout.write(JSON.stringify(report, null, 2) + '\n');
@@ -1370,7 +1375,7 @@ if (args[0] === 'sbom' || args[0] === 'manifest' || args[0] === 'verify') {
         console.log(`    ✓ ok:       ${s.ok}`);
         console.log(`    ✗ modified: ${s.modified}`);
         console.log(`    ✗ missing:  ${s.missing}`);
-        console.log(`    ⚠ extra:    ${s.extra} (advisory)`);
+        console.log(`    ⚠ extra:    ${s.extra} ${strict ? '(fails verify: --strict)' : '(advisory — use --strict to fail on these)'}`);
 
         if (report.details.modified.length) {
           console.log(`\nModified files:`);
@@ -1724,6 +1729,7 @@ if (args.includes('--help') || args.includes('-h')) {
     npx kodelyth-ecc sbom [--out file.json]       Emit a CycloneDX 1.5 SBOM for the package
     npx kodelyth-ecc manifest [--out file.json]   Emit a sha256 content manifest of all assets
     npx kodelyth-ecc verify [--manifest file]     Verify installed copy against a content manifest
+    npx kodelyth-ecc verify --strict              ...and fail on unexpected extra files too
     npx kodelyth-ecc evolve analyze               Generate skill / routing proposals from memory + miss signals
     npx kodelyth-ecc dashboard                    Boot localhost-only observability dashboard (zero telemetry)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kodelyth-ecc",
-  "version": "2.24.7",
+  "version": "2.24.9",
   "description": "Production-grade AI coding toolkit — 70 agents (incl. devil-mode adversarial crew), 196 skills, 103 commands, parallel multi-agent commands, semantic intent routing, self-learning memory, and a built-in MCP server (16 tools / 6 prompts / 377 resources) that bridges to Claude Desktop, LangGraph, AutoGen, CrewAI, and OpenAI Agents SDK. Works on macOS, Linux and Windows with Claude Code, Windsurf, Cursor, Codex, Antigravity, OpenCode, Cline, RooCode, Aider, Kimi, and Gemini CLI.",
   "author": "Kodelyth <github.com/sifxprime>",
   "license": "MIT",

package/scripts/dashboard/data.js

@@ -335,10 +335,36 @@ function sessionDetail({ session, coordRoot = defaultCoordRoot() } = {}) {
 }
 
 function safeReadExcerpt(p, max = 800) {
+  // Reads only the window it needs. This used to readFileSync the WHOLE file and
+  // then slice 800 characters off the front, which meant a large file in a
+  // coordination directory cost its full size in time and memory to produce a
+  // fixed-size excerpt. Measured: a 300MB task.md took 693ms and +733MB RSS to
+  // return 800 characters, scaling linearly — and the dashboard is single
+  // threaded, so that blocks every other request. It is called three times per
+  // worker (task, handoff, status) across every session, so the cost multiplies.
+  //
+  // The window is max*4 bytes because UTF-8 encodes a character in at most four,
+  // so it always contains at least `max` characters when the file has them. That
+  // matters: the truncation decision below counts CHARACTERS, as it always did,
+  // so slicing a byte window would otherwise cut a multi-byte character in half
+  // and change the output for any non-ASCII file.
+  let fd;
   try {
-    const content = fs.readFileSync(p, 'utf8');
+    const st = fs.statSync(p);
+    if (!st.isFile()) return null;
+    const window = Math.min(st.size, max * 4 + 4);
+    const buf = Buffer.alloc(window);
+    fd = fs.openSync(p, 'r');
+    const bytesRead = fs.readSync(fd, buf, 0, window, 0);
+    const content = buf.subarray(0, bytesRead).toString('utf8');
     return content.length > max ? content.slice(0, max) + '\n…(truncated)' : content;
-  } catch { return null; }
+  } catch {
+    return null;
+  } finally {
+    if (fd !== undefined) {
+      try { fs.closeSync(fd); } catch { /* already gone */ }
+    }
+  }
 }
 
 // ── IDE sessions (Claude Code / Windsurf / Antigravity) ──────────────────────

package/scripts/lib/tmux-worktree-orchestrator.js

@@ -183,7 +183,25 @@ function buildOrchestrationPlan(config = {}) {
     config.coordinationRoot || path.join(repoRoot, '.orchestration')
   );
   const coordinationDir = path.join(coordinationRoot, sessionName);
+  // baseRef is the only value in this file that reaches a command's argv without
+  // being slugified or path-resolved first. Every spawn here uses the array form
+  // with no shell, which stops shell injection — but it does NOT stop ARGUMENT
+  // injection: git parses argv itself, so a ref beginning with "-" is read as an
+  // option rather than a commit-ish. In
+  //     git worktree add -b <branch> <path> <commit-ish>
+  // a baseRef of "--git-dir=/elsewhere" silently redirects git at another
+  // repository, and "--force" changes the command's meaning. It is user-settable
+  // through --base-ref, and swarm configs get shared, so it is not only
+  // self-inflicted.
+  //
+  // Rejecting a leading "-" is enough: git refs cannot begin with one anyway
+  // (git check-ref-format forbids it), so nothing legitimate is lost.
   const baseRef = config.baseRef || 'HEAD';
+  if (typeof baseRef !== 'string' || baseRef.startsWith('-')) {
+    throw new Error(
+      `baseRef must be a ref name, not an option: ${JSON.stringify(String(baseRef))}`
+    );
+  }
   const defaultLauncher = config.launcherCommand || '';
 
   if (workers.length === 0) {

package/scripts/mcp/register-self.js

@@ -7,6 +7,7 @@
 'use strict';
 
 const fs   = require('fs');
+const safeFs = require('../lib/safe-fs');
 const os   = require('os');
 const path = require('path');
 
@@ -24,13 +25,48 @@ function claudeDesktopConfigPath() {
   return path.join(home, '.config', 'Claude', 'claude_desktop_config.json');
 }
 
-function readJson(file) {
-  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; }
+// Reading this file has THREE outcomes, and collapsing them is destructive.
+//
+// readJson used to return null for every failure, and the caller did
+// `readJson(file) || {}`. So a config that merely failed to parse — one trailing
+// comma from a hand-edit, a half-written file, a bad mount — was treated as an
+// empty config, and the merge wrote it back containing only ECC's own entry.
+// Measured on a realistic config: 366 bytes in, 140 bytes out, with every other
+// MCP server, every project entry and every setting gone. Silently, during an
+// install the user did not think was risky.
+//
+// Absent is safe to treat as empty. Unreadable is not.
+function readConfig(file) {
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return { state: 'absent', data: {} };
+    return { state: 'unreadable', reason: err.message };
+  }
+  // An empty or whitespace-only file is effectively absent; JSON.parse would
+  // throw on it and we would otherwise refuse to ever register.
+  if (raw.trim() === '') return { state: 'absent', data: {} };
+  try {
+    const data = JSON.parse(raw);
+    if (!data || typeof data !== 'object' || Array.isArray(data)) {
+      return { state: 'unreadable', reason: 'top-level value is not an object' };
+    }
+    return { state: 'present', data };
+  } catch (err) {
+    return { state: 'unreadable', reason: err.message };
+  }
 }
 
 function writeJson(file, obj) {
   fs.mkdirSync(path.dirname(file), { recursive: true });
-  fs.writeFileSync(file, JSON.stringify(obj, null, 2));
+  // Atomic: write a temp file and rename. A crash or a full disk partway through
+  // a plain writeFileSync leaves the user with a truncated config, which is the
+  // same data loss by a different route.
+  // PreservingMode rather than Atomic: this is the user's own config file and it
+  // may carry permissions they chose. It keeps the existing mode when the file is
+  // already there and falls back to 0644 when creating it.
+  safeFs.replaceFilePreservingMode(file, JSON.stringify(obj, null, 2) + '\n');
 }
 
 function serverEntry() {
@@ -42,7 +78,15 @@ function serverEntry() {
 }
 
 function registerInFile(file, opts = {}) {
-  const existing = readJson(file) || {};
+  const cfg = readConfig(file);
+  if (cfg.state === 'unreadable') {
+    // Refusing is the whole point. Overwriting would destroy whatever is in there.
+    throw new Error(
+      `refusing to modify ${file}: it exists but could not be parsed (${cfg.reason}). ` +
+      `Fix or move the file, then re-run. Nothing was written.`
+    );
+  }
+  const existing = cfg.data;
   const servers = existing.mcpServers || {};
   const already = servers[SERVER_NAME];
   const desired = serverEntry();
@@ -56,7 +100,10 @@ function registerInFile(file, opts = {}) {
 }
 
 function unregisterInFile(file) {
-  const existing = readJson(file);
+  const cfg = readConfig(file);
+  // Same rule on the way out: an unparseable config is left exactly as it is.
+  if (cfg.state === 'unreadable') return { file, action: 'skipped-unreadable', reason: cfg.reason };
+  const existing = cfg.data;
   if (!existing || !existing.mcpServers || !existing.mcpServers[SERVER_NAME]) {
     return { file, action: 'not-present' };
   }
@@ -113,4 +160,7 @@ module.exports = {
   registerAll,
   unregisterAll,
   statusAll,
+  // Exported for tests: these must be exercisable without writing to a real
+  // ~/.claude.json, and the whole point of the fix is what they refuse to do.
+  _internals: { readConfig, registerInFile, unregisterInFile },
 };

package/scripts/supply-chain/verify.js

@@ -23,7 +23,7 @@ const { hashFile, walkFiles, MANIFEST_SCHEMA } = require('./manifest.js');
 
 const VERIFY_RESULT_KEYS = ['ok', 'modified', 'missing', 'extra'];
 
-function verifyAgainstManifest({ rootDir, manifest } = {}) {
+function verifyAgainstManifest({ rootDir, manifest, strict = false } = {}) {
   if (!rootDir)  throw new Error('verifyAgainstManifest: rootDir is required');
   if (!manifest) throw new Error('verifyAgainstManifest: manifest is required');
   if (manifest.schema !== MANIFEST_SCHEMA) {
@@ -81,11 +81,27 @@ function verifyAgainstManifest({ rootDir, manifest } = {}) {
     extra:    extraFiles.length,
   };
 
-  // verify is "ok" if no missing and no modified files. Extras are non-fatal.
-  const ok = summary.missing === 0 && summary.modified === 0;
+  // By default an EXTRA file is advisory: it does not fail the verdict. That is
+  // deliberate and correct for a toolkit people are meant to extend — anyone who
+  // has added their own agent or skill would otherwise see verify fail forever.
+  //
+  // It is the wrong default for automation, though. A planted file returns ok
+  // true and exit code 0, so `verify && deploy` passes with an unknown file in
+  // place — and in this product an extra .md under rules/, agents/ or commands/
+  // is not inert data, it is loaded as instructions, so an injected
+  // rules/common/zz.md becomes an always-on rule. Confirmed: a clean tree reports
+  // ok true, planting that file still reports ok true with extra 1.
+  //
+  // So the choice is offered rather than made. strict folds extras into the
+  // verdict for callers that want a gate; the default is unchanged.
+  const ok =
+    summary.missing === 0 &&
+    summary.modified === 0 &&
+    (!strict || summary.extra === 0);
 
   return {
     ok,
+    strict,
     summary,
     details: {
       ok:       okFiles,