everything-claude-code 1.4.3 → 1.4.4

package/crates/ecc-kernel/src/main.rs

@@ -7,6 +7,17 @@ use std::process::{Command, ExitCode, Stdio};
 use time::format_description::well_known::Rfc3339;
 use time::OffsetDateTime;
 
+const PROTOCOL_VERSION: i32 = 1;
+const COMMANDS: &[&str] = &[
+    "worktree.ensure",
+    "worktree.remove",
+    "patch.apply",
+    "git.commit_all",
+    "verify.run",
+    "protocol.version",
+    "repo.info",
+];
+
 fn now_iso() -> String {
     OffsetDateTime::now_utc()
         .format(&Rfc3339)
@@ -502,6 +513,127 @@ fn commit_all(input: CommitAllIn) -> Result<CommitAllOut, String> {
     })
 }
 
+#[derive(Deserialize)]
+struct ProtocolVersionIn {}
+
+#[derive(Serialize)]
+struct ProtocolVersionOut {
+    version: i32,
+    protocol: i32,
+    kernelVersion: String,
+    commands: Vec<String>,
+}
+
+fn protocol_version(_input: ProtocolVersionIn) -> Result<ProtocolVersionOut, String> {
+    Ok(ProtocolVersionOut {
+        version: 1,
+        protocol: PROTOCOL_VERSION,
+        kernelVersion: env!("CARGO_PKG_VERSION").to_string(),
+        commands: COMMANDS.iter().map(|s| s.to_string()).collect(),
+    })
+}
+
+#[derive(Deserialize)]
+struct RepoInfoIn {
+    cwd: String,
+}
+
+#[derive(Serialize)]
+struct RepoInfoOut {
+    version: i32,
+    repoRoot: Option<String>,
+    branch: String,
+    sha: String,
+    clean: bool,
+}
+
+fn repo_info(input: RepoInfoIn) -> Result<RepoInfoOut, String> {
+    let cwd = PathBuf::from(input.cwd);
+
+    let out_root = run_git(
+        &vec![
+            "-C".to_string(),
+            cwd.display().to_string(),
+            "rev-parse".to_string(),
+            "--show-toplevel".to_string(),
+        ],
+        None,
+    )?;
+
+    if !out_root.ok {
+        return Ok(RepoInfoOut {
+            version: 1,
+            repoRoot: None,
+            branch: "".to_string(),
+            sha: "".to_string(),
+            clean: false,
+        });
+    }
+
+    let repo_root = out_root.stdout.trim().to_string();
+
+    let out_branch = run_git(
+        &vec![
+            "-C".to_string(),
+            repo_root.clone(),
+            "rev-parse".to_string(),
+            "--abbrev-ref".to_string(),
+            "HEAD".to_string(),
+        ],
+        None,
+    )?;
+    if !out_branch.ok {
+        return Err(out_branch
+            .stderr
+            .is_empty()
+            .then(|| "git rev-parse --abbrev-ref HEAD failed".to_string())
+            .unwrap_or(out_branch.stderr));
+    }
+
+    let out_sha = run_git(
+        &vec![
+            "-C".to_string(),
+            repo_root.clone(),
+            "rev-parse".to_string(),
+            "HEAD".to_string(),
+        ],
+        None,
+    )?;
+    if !out_sha.ok {
+        return Err(out_sha
+            .stderr
+            .is_empty()
+            .then(|| "git rev-parse HEAD failed".to_string())
+            .unwrap_or(out_sha.stderr));
+    }
+
+    let out_status = run_git(
+        &vec![
+            "-C".to_string(),
+            repo_root.clone(),
+            "status".to_string(),
+            "--porcelain".to_string(),
+            "--untracked-files=no".to_string(),
+        ],
+        None,
+    )?;
+    if !out_status.ok {
+        return Err(out_status
+            .stderr
+            .is_empty()
+            .then(|| "git status --porcelain failed".to_string())
+            .unwrap_or(out_status.stderr));
+    }
+
+    Ok(RepoInfoOut {
+        version: 1,
+        repoRoot: Some(repo_root),
+        branch: out_branch.stdout.trim().to_string(),
+        sha: out_sha.stdout.trim().to_string(),
+        clean: out_status.stdout.trim().is_empty(),
+    })
+}
+
 #[derive(Deserialize)]
 struct VerifyCmdIn {
     name: String,
@@ -628,6 +760,7 @@ fn verify_run(input: VerifyRunIn) -> Result<VerifySummaryOut, String> {
 }
 
 fn usage() {
+    let cmds = COMMANDS.join("\n  ");
     eprintln!(
         r#"ecc-kernel
 
@@ -635,12 +768,10 @@ Usage:
   ecc-kernel <command>   (JSON input on stdin; JSON output on stdout)
 
 Commands:
-  worktree.ensure
-  worktree.remove
-  patch.apply
-  git.commit_all
-  verify.run
+  {cmds}
 "#
+        ,
+        cmds = cmds
     );
 }
 
@@ -686,6 +817,16 @@ fn real_main() -> Result<(), String> {
       let out = commit_all(input)?;
       write_stdout_json(&out)
     }
+    "protocol.version" => {
+      let input: ProtocolVersionIn = read_stdin_json()?;
+      let out = protocol_version(input)?;
+      write_stdout_json(&out)
+    }
+    "repo.info" => {
+      let input: RepoInfoIn = read_stdin_json()?;
+      let out = repo_info(input)?;
+      write_stdout_json(&out)
+    }
     "verify.run" => {
       let input: VerifyRunIn = read_stdin_json()?;
       let out = verify_run(input)?;
@@ -708,3 +849,111 @@ fn main() -> ExitCode {
     }
   }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn tmp_dir(prefix: &str) -> PathBuf {
+        let mut dir = std::env::temp_dir();
+        dir.push(format!(
+            "{}-{}-{}",
+            prefix,
+            std::process::id(),
+            OffsetDateTime::now_utc().unix_timestamp_nanos()
+        ));
+        dir
+    }
+
+    fn git(repo: &Path, args: &[&str]) -> Result<CmdOut, String> {
+        let mut v: Vec<String> = Vec::new();
+        v.push("-C".to_string());
+        v.push(repo.display().to_string());
+        for a in args {
+            v.push(a.to_string());
+        }
+        run_git(&v, None)
+    }
+
+    fn init_git_repo(repo: &Path) -> Result<(), String> {
+        fs::create_dir_all(repo).map_err(|e| format!("mkdir failed: {e}"))?;
+        let out = git(repo, &["init"])?;
+        if !out.ok {
+            return Err(out.stderr);
+        }
+
+        // Ensure commits work in CI.
+        let _ = git(repo, &["config", "user.email", "ecc@example.com"])?;
+        let _ = git(repo, &["config", "user.name", "ECC"])?;
+
+        fs::write(repo.join("base.txt"), "base\n").map_err(|e| format!("write failed: {e}"))?;
+        let out_add = git(repo, &["add", "-A"])?;
+        if !out_add.ok {
+            return Err(out_add.stderr);
+        }
+        let out_commit = git(repo, &["commit", "-m", "init"])?;
+        if !out_commit.ok {
+            return Err(out_commit.stderr);
+        }
+        Ok(())
+    }
+
+    #[test]
+    fn protocol_version_has_required_fields() {
+        let out = protocol_version(ProtocolVersionIn {}).unwrap();
+        assert_eq!(out.version, 1);
+        assert_eq!(out.protocol, PROTOCOL_VERSION);
+        assert!(!out.kernelVersion.trim().is_empty());
+
+        let cmds: std::collections::BTreeSet<String> = out.commands.into_iter().collect();
+        for c in COMMANDS.iter() {
+            assert!(cmds.contains(&c.to_string()), "missing command: {c}");
+        }
+    }
+
+    #[test]
+    fn repo_info_returns_repo_details_and_cleanliness() {
+        let dir = tmp_dir("ecc-kernel-test-repo");
+        let res = init_git_repo(&dir);
+        assert!(res.is_ok(), "init_git_repo failed: {:?}", res.err());
+
+        let info = repo_info(RepoInfoIn {
+            cwd: dir.display().to_string(),
+        })
+        .unwrap();
+
+        assert_eq!(info.version, 1);
+        let got_root = info.repoRoot.clone().unwrap();
+        let expected_abs = fs::canonicalize(&dir).unwrap();
+        let got_abs = fs::canonicalize(std::path::Path::new(&got_root)).unwrap();
+        assert_eq!(got_abs, expected_abs);
+        assert!(!info.branch.trim().is_empty());
+        assert_eq!(info.sha.len(), 40);
+        assert_eq!(info.clean, true);
+
+        // Modifying a tracked file should mark repo as dirty.
+        fs::write(dir.join("base.txt"), "changed\n").unwrap();
+        let info2 = repo_info(RepoInfoIn {
+            cwd: dir.display().to_string(),
+        })
+        .unwrap();
+        assert_eq!(info2.clean, false);
+
+        let _ = fs::remove_dir_all(&dir);
+    }
+
+    #[test]
+    fn repo_info_outside_repo_is_null() {
+        let dir = tmp_dir("ecc-kernel-test-norepo");
+        fs::create_dir_all(&dir).unwrap();
+
+        let info = repo_info(RepoInfoIn {
+            cwd: dir.display().to_string(),
+        })
+        .unwrap();
+        assert_eq!(info.version, 1);
+        assert!(info.repoRoot.is_none());
+
+        let _ = fs::remove_dir_all(&dir);
+    }
+}

package/docs/ecc-kernel-protocol.md

@@ -0,0 +1,106 @@
+# ecc-kernel Protocol
+
+`ecc-kernel` is a small Rust binary that offloads ECC "kernel" operations:
+- git worktree creation/removal
+- safe patch apply with ownership checks
+- verify command runner (writes evidence files)
+
+All commands use:
+- **stdin**: JSON
+- **stdout**: JSON
+- **stderr**: human-readable diagnostics
+
+---
+
+## Versioning and Compatibility
+
+- Node and kernel communicate via a protocol handshake.
+- Node expects `protocol=1` and the required command set.
+- `ECC_KERNEL=auto` falls back to JS if handshake fails.
+- `ECC_KERNEL=rust` fails fast if handshake fails.
+
+---
+
+## Command: `protocol.version`
+
+### Input (stdin JSON)
+
+```json
+{}
+```
+
+### Output (stdout JSON)
+
+```json
+{
+  "version": 1,
+  "protocol": 1,
+  "kernelVersion": "0.1.0",
+  "commands": [
+    "worktree.ensure",
+    "worktree.remove",
+    "patch.apply",
+    "git.commit_all",
+    "verify.run",
+    "protocol.version",
+    "repo.info"
+  ]
+}
+```
+
+Fields:
+- `version`: output schema version (currently `1`)
+- `protocol`: protocol version (currently `1`)
+- `kernelVersion`: Rust crate version
+- `commands`: supported command identifiers
+
+---
+
+## Command: `repo.info`
+
+Returns git repo information for a given `cwd`.
+
+### Input
+
+```json
+{ "cwd": "/path/to/dir" }
+```
+
+### Output (inside a git repo)
+
+```json
+{
+  "version": 1,
+  "repoRoot": "/path/to/repo",
+  "branch": "main",
+  "sha": "0123456789abcdef0123456789abcdef01234567",
+  "clean": true
+}
+```
+
+### Output (not a git repo)
+
+```json
+{
+  "version": 1,
+  "repoRoot": null,
+  "branch": "",
+  "sha": "",
+  "clean": false
+}
+```
+
+Notes:
+- `clean` ignores untracked files (equivalent to `git status --porcelain --untracked-files=no`).
+
+---
+
+## Other Commands
+
+The remaining commands are internal engine plumbing and are documented by source:
+- `worktree.ensure`
+- `worktree.remove`
+- `patch.apply`
+- `git.commit_all`
+- `verify.run`
+

package/docs/ecc-release.md

@@ -0,0 +1,82 @@
+# ECC Release Guide
+
+This repo ships ECC as a Node CLI with an optional Rust kernel (`ecc-kernel`).
+
+The release chain is designed to make installs reliable:
+- Tag push builds and uploads prebuilt kernels to a GitHub Release
+- npm publish validates those assets exist (so installs can download them)
+- Release smoke tests validate real install + download + run across OSes
+
+---
+
+## Versioning
+
+- `package.json.version` must match the git tag: `v${version}`
+- Use patch bumps by default.
+
+---
+
+## Release Steps (vX.Y.Z)
+
+1. Ensure `main` is green (CI passes).
+2. Bump version (on `main`):
+
+   ```bash
+   npm version patch --no-git-tag-version
+   ```
+
+3. Commit:
+
+   ```bash
+   git commit -am "chore(release): vX.Y.Z"
+   ```
+
+4. Tag + push:
+
+   ```bash
+   git tag vX.Y.Z
+   git push origin main
+   git push origin vX.Y.Z
+   ```
+
+5. Verify GitHub Release:
+- Workflow: `.github/workflows/release.yml`
+- Assets must include `ecc-kernel-<os>-<arch>[.exe]` plus `.sha256` files.
+
+6. Verify Release Smoke:
+- Workflow: `.github/workflows/release-smoke.yml`
+- Runs a real install from a packed tarball and exercises:
+  - `ECC_KERNEL_INSTALL=required` + `ECC_KERNEL=rust`
+  - `ECC_KERNEL_INSTALL=0` + `ECC_KERNEL=node`
+
+7. Publish to npm:
+- Workflow: `.github/workflows/publish-npm.yml`
+- Uses npm Trusted Publishing (OIDC) if configured, with optional `NPM_TOKEN` fallback.
+
+---
+
+## Troubleshooting
+
+### Release created but assets missing / 404 during install
+- Kernel upload can be briefly eventual-consistent.
+- Re-run smoke (workflow_dispatch) after a minute:
+
+  ```bash
+  gh workflow run "Release Smoke" -f tag=vX.Y.Z
+  ```
+
+### npm publish fails (OIDC not configured)
+- Configure npm "Trusted Publisher" for:
+  - owner: `sumulige`
+  - repo: `everything-claude-code`
+  - workflow file: `publish-npm.yml`
+- Re-run publish:
+
+  ```bash
+  gh workflow run "Publish (npm)" -f tag=vX.Y.Z
+  ```
+
+### Rollback
+- If a bad version is published to npm: publish a new patch version.
+- If a GitHub Release is broken: re-run `Release` workflow for the same tag, or create a new tag.
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "everything-claude-code",
-  "version": "1.4.3",
+  "version": "1.4.4",
   "description": "Everything Claude Code + ECC (Engineering Change Conveyor) CLI",
   "license": "MIT",
   "repository": {
@@ -27,6 +27,8 @@
     "schemas/",
     "prompts/ecc/",
     "docs/ecc.md",
+    "docs/ecc-release.md",
+    "docs/ecc-kernel-protocol.md",
     "README.md",
     "LICENSE"
   ],

package/scripts/ecc/git.js

@@ -4,6 +4,7 @@ const path = require('path');
 const { spawnSync } = require('child_process');
 
 const { runKernel } = require('./kernel');
+const { validateRepoInfoOutput } = require('./kernel-contract');
 
 function runGit(args, opts = {}) {
   const res = spawnSync('git', args, {
@@ -123,9 +124,34 @@ function commitAll({ repoRoot, message }) {
   return sha;
 }
 
+function getRepoInfo(cwd) {
+  const kernelOut = runKernel('repo.info', { cwd });
+  if (kernelOut !== null) {
+    const errors = validateRepoInfoOutput(kernelOut);
+    if (errors.length) {
+      throw new Error(`ecc-kernel repo.info returned invalid output: ${errors.join('; ')}`);
+    }
+    return kernelOut;
+  }
+
+  const repoRoot = getRepoRoot(cwd);
+  if (!repoRoot) {
+    return { version: 1, repoRoot: null, branch: '', sha: '', clean: false };
+  }
+
+  return {
+    version: 1,
+    repoRoot,
+    branch: getCurrentBranch(repoRoot),
+    sha: getHeadSha(repoRoot),
+    clean: isClean(repoRoot)
+  };
+}
+
 module.exports = {
   runGit,
   getRepoRoot,
+  getRepoInfo,
   getHeadSha,
   getCurrentBranch,
   isClean,

package/scripts/ecc/install-kernel.js

@@ -21,6 +21,8 @@ const crypto = require('crypto');
 const { spawnSync } = require('child_process');
 const { URL } = require('url');
 
+const { EXPECTED_PROTOCOL, validateProtocolVersionOutput } = require('./kernel-contract');
+
 function debugEnabled() {
   return !!(process.env.ECC_KERNEL_DEBUG && String(process.env.ECC_KERNEL_DEBUG).trim());
 }
@@ -247,6 +249,34 @@ function validateRuns(filePath) {
   }
 }
 
+function validateProtocol(filePath) {
+  const res = spawnSync(filePath, ['protocol.version'], {
+    encoding: 'utf8',
+    input: '{}',
+    stdio: ['pipe', 'pipe', 'pipe']
+  });
+  if (res.error) throw new Error(`kernel protocol.version failed: ${res.error.message}`);
+  if (res.status !== 0) {
+    const stderr = (res.stderr || '').trim();
+    throw new Error(`kernel protocol.version failed (exit ${res.status})${stderr ? `: ${stderr}` : ''}`);
+  }
+
+  const stdout = (res.stdout || '').trim();
+  if (!stdout) throw new Error('kernel protocol.version returned empty output');
+
+  let obj;
+  try {
+    obj = JSON.parse(stdout);
+  } catch (_err) {
+    throw new Error('kernel protocol.version returned non-JSON output');
+  }
+
+  const errors = validateProtocolVersionOutput(obj, { expectedProtocol: EXPECTED_PROTOCOL });
+  if (errors.length) {
+    throw new Error(`kernel protocol.version invalid: ${errors.join('; ')}`);
+  }
+}
+
 async function main() {
   const { mode, envSet } = parseInstallMode();
   if (mode === 'off') return;
@@ -273,7 +303,15 @@ async function main() {
 
   if (fs.existsSync(destBin)) {
     logDebug(`kernel already present: ${destBin}`);
-    return;
+    try {
+      ensureExecutable(destBin);
+      validateRuns(destBin);
+      validateProtocol(destBin);
+      return;
+    } catch (err) {
+      logDebug(`existing kernel invalid/outdated, reinstalling: ${err.message}`);
+      try { fs.rmSync(destBin, { force: true }); } catch (_err) { /* ignore */ }
+    }
   }
 
   const baseUrl = defaultBaseUrl(version, pkg);
@@ -327,6 +365,7 @@ async function main() {
     }
 
     validateRuns(destBin);
+    validateProtocol(destBin);
   } catch (err) {
     try { fs.rmSync(destBin, { force: true }); } catch (_err) { /* ignore */ }
     if (mode === 'required') throw err;

package/scripts/ecc/kernel-contract.js

@@ -0,0 +1,63 @@
+function isObj(v) {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+function isInt(v) {
+  return Number.isInteger(v);
+}
+
+const EXPECTED_PROTOCOL = 1;
+
+// Commands that the Node engine expects the Rust kernel to support.
+const REQUIRED_COMMANDS = [
+  'worktree.ensure',
+  'worktree.remove',
+  'patch.apply',
+  'git.commit_all',
+  'verify.run',
+  'protocol.version',
+  'repo.info'
+];
+
+function validateProtocolVersionOutput(obj, { expectedProtocol = EXPECTED_PROTOCOL } = {}) {
+  const errors = [];
+  if (!isObj(obj)) return ['expected object'];
+
+  if (obj.version !== 1) errors.push('expected version: 1');
+
+  if (!isInt(obj.protocol)) errors.push('expected protocol: integer');
+  else if (obj.protocol !== expectedProtocol) errors.push(`protocol mismatch: expected ${expectedProtocol}, got ${obj.protocol}`);
+
+  if (typeof obj.kernelVersion !== 'string' || !obj.kernelVersion.trim()) errors.push('expected kernelVersion: non-empty string');
+
+  if (!Array.isArray(obj.commands)) {
+    errors.push('expected commands: array');
+  } else {
+    const missing = REQUIRED_COMMANDS.filter(c => !obj.commands.includes(c));
+    if (missing.length) errors.push(`missing commands: ${missing.join(', ')}`);
+  }
+
+  return errors;
+}
+
+function validateRepoInfoOutput(obj) {
+  const errors = [];
+  if (!isObj(obj)) return ['expected object'];
+
+  if (obj.version !== 1) errors.push('expected version: 1');
+
+  if (obj.repoRoot !== null && typeof obj.repoRoot !== 'string') errors.push('expected repoRoot: string|null');
+  if (typeof obj.branch !== 'string') errors.push('expected branch: string');
+  if (typeof obj.sha !== 'string') errors.push('expected sha: string');
+  if (typeof obj.clean !== 'boolean') errors.push('expected clean: boolean');
+
+  return errors;
+}
+
+module.exports = {
+  EXPECTED_PROTOCOL,
+  REQUIRED_COMMANDS,
+  validateProtocolVersionOutput,
+  validateRepoInfoOutput
+};
+

package/scripts/ecc/kernel.js

@@ -2,6 +2,8 @@ const fs = require('fs');
 const path = require('path');
 const { spawnSync } = require('child_process');
 
+const { EXPECTED_PROTOCOL, validateProtocolVersionOutput } = require('./kernel-contract');
+
 function isFile(p) {
   try {
     return fs.statSync(p).isFile();
@@ -47,36 +49,139 @@ function tryKernelFromPath() {
     encoding: 'utf8',
     stdio: ['ignore', 'pipe', 'pipe']
   });
-  if (res.error) return null;
-  if (res.status === 0) return 'ecc-kernel';
-  return null;
+  if (res.error) {
+    // ENOENT means not on PATH; treat as no candidate.
+    if (res.error && res.error.code === 'ENOENT') return null;
+    // Other spawn errors still indicate an attemptable candidate (will be probed for a better error).
+    return 'ecc-kernel';
+  }
+  return 'ecc-kernel';
+}
+
+function runKernelJson(bin, command, inputObj) {
+  const res = spawnSync(bin, [command], {
+    encoding: 'utf8',
+    input: JSON.stringify(inputObj || {}),
+    stdio: ['pipe', 'pipe', 'pipe']
+  });
+
+  if (res.error) return { ok: false, error: `spawn failed: ${res.error.message}` };
+  const stdout = (res.stdout || '').trim();
+  const stderr = (res.stderr || '').trim();
+
+  if (res.status !== 0) {
+    const detail = stderr ? `stderr: ${stderr}` : (stdout ? `stdout: ${stdout}` : '');
+    return { ok: false, error: `exit ${res.status}${detail ? ` (${detail})` : ''}` };
+  }
+
+  if (!stdout) return { ok: false, error: 'empty stdout' };
+  try {
+    return { ok: true, value: JSON.parse(stdout) };
+  } catch (err) {
+    const msg = err && err.message ? err.message : String(err);
+    return { ok: false, error: `non-JSON stdout (${msg})` };
+  }
+}
+
+function probeKernel(bin) {
+  const res = runKernelJson(bin, 'protocol.version', {});
+  if (!res.ok) return { ok: false, error: `protocol.version failed: ${res.error}` };
+
+  const errors = validateProtocolVersionOutput(res.value, { expectedProtocol: EXPECTED_PROTOCOL });
+  if (errors.length) {
+    return { ok: false, error: `invalid protocol.version output: ${errors.join('; ')}` };
+  }
+
+  return {
+    ok: true,
+    protocol: res.value.protocol,
+    kernelVersion: res.value.kernelVersion,
+    commands: res.value.commands
+  };
 }
 
-function findKernelBinary() {
+function candidateList() {
+  const candidates = [];
+
   if (process.env.ECC_KERNEL_PATH) {
-    const p = path.resolve(String(process.env.ECC_KERNEL_PATH));
-    if (isFile(p)) return p;
+    candidates.push({
+      label: 'ECC_KERNEL_PATH',
+      bin: path.resolve(String(process.env.ECC_KERNEL_PATH)),
+      requiresFile: true,
+      explicit: true
+    });
   }
 
   // Preferred location for prebuilt binaries installed via postinstall.
   const key = platformArchKey();
   if (key) {
-    const packaged = path.join(__dirname, 'bin', key, binName());
-    if (isFile(packaged)) return packaged;
+    candidates.push({
+      label: 'package',
+      bin: path.join(__dirname, 'bin', key, binName()),
+      requiresFile: true,
+      explicit: false
+    });
   }
 
+  // PATH lookup.
   const fromPath = tryKernelFromPath();
-  if (fromPath) return fromPath;
+  if (fromPath) {
+    candidates.push({ label: 'PATH', bin: fromPath, requiresFile: false, explicit: false });
+  }
 
+  // Local dev build (repo).
   const root = path.resolve(__dirname, '..', '..');
-  const candidates = [
-    path.join(root, 'crates', 'ecc-kernel', 'target', 'release', binName()),
-    path.join(root, 'crates', 'ecc-kernel', 'target', 'debug', binName())
-  ];
-  for (const p of candidates) {
-    if (isFile(p)) return p;
+  candidates.push({
+    label: 'repo-release',
+    bin: path.join(root, 'crates', 'ecc-kernel', 'target', 'release', binName()),
+    requiresFile: true,
+    explicit: false
+  });
+  candidates.push({
+    label: 'repo-debug',
+    bin: path.join(root, 'crates', 'ecc-kernel', 'target', 'debug', binName()),
+    requiresFile: true,
+    explicit: false
+  });
+
+  const seen = new Set();
+  return candidates.filter(c => {
+    if (seen.has(c.bin)) return false;
+    seen.add(c.bin);
+    return true;
+  });
+}
+
+function selectCompatibleKernel({ mode }) {
+  const candidates = candidateList();
+  const errors = [];
+
+  for (const c of candidates) {
+    if (c.requiresFile && !isFile(c.bin)) {
+      if (c.explicit && mode === 'rust') {
+        throw new Error(`ECC kernel required but ECC_KERNEL_PATH is not a file: ${c.bin}`);
+      }
+      continue;
+    }
+
+    const probe = probeKernel(c.bin);
+    if (probe.ok) return { enabled: true, bin: c.bin, ...probe };
+
+    errors.push(`${c.label}: ${probe.error}`);
+    if (c.explicit && mode === 'rust') break;
+  }
+
+  if (mode === 'rust') {
+    const detail = errors.length ? `\n\nHandshake errors:\n- ${errors.join('\n- ')}` : '';
+    throw new Error(
+      'ECC kernel required but not found or incompatible.\n' +
+        'Install or build a compatible ecc-kernel, then re-run, or set ECC_KERNEL=node to force JS fallback.' +
+        detail
+    );
   }
-  return null;
+
+  // mode=auto: fall back to JS. If we saw a kernel but it was incompatible, keep the reason for doctor output.
+  return { enabled: false, bin: null, reason: errors.length ? errors[0] : null };
 }
 
 let _cached = null;
@@ -86,20 +191,25 @@ function getKernel() {
 
   const mode = getKernelMode();
   if (mode === 'node') {
-    _cached = { mode, enabled: false, bin: null };
+    _cached = { mode, enabled: false, bin: null, reason: null };
     return _cached;
   }
 
-  const bin = findKernelBinary();
-  if (mode === 'rust' && !bin) {
-    throw new Error(
-      'ECC kernel required but not found. Build it with:\n' +
-        '  cargo build --release --manifest-path crates/ecc-kernel/Cargo.toml\n' +
-        'Then re-run, or set ECC_KERNEL=node to force JS fallback.'
-    );
+  const selected = selectCompatibleKernel({ mode });
+  if (!selected.enabled) {
+    _cached = { mode, enabled: false, bin: null, reason: selected.reason };
+    return _cached;
   }
 
-  _cached = { mode, enabled: !!bin, bin };
+  _cached = {
+    mode,
+    enabled: true,
+    bin: selected.bin,
+    protocol: selected.protocol,
+    kernelVersion: selected.kernelVersion,
+    commands: selected.commands,
+    reason: null
+  };
   return _cached;
 }
 
@@ -140,5 +250,6 @@ function runKernel(command, inputObj) {
 
 module.exports = {
   getKernel,
-  runKernel
+  runKernel,
+  validateProtocolVersionOutput
 };

package/scripts/ecc.js

@@ -82,7 +82,8 @@ Environment:
 
 function resolveProjectRoot(cwd) {
   try {
-    return git.getRepoRoot(cwd) || cwd;
+    const info = git.getRepoInfo(cwd);
+    return info && info.repoRoot ? info.repoRoot : cwd;
   } catch (_err) {
     return cwd;
   }
@@ -181,8 +182,15 @@ function cmdDoctor() {
 
   try {
     const k = kernel.getKernel();
-    const detail = k.enabled ? `rust (${k.bin})` : 'js fallback';
-    checks.push({ name: 'kernel', ok: true, detail });
+    if (k.enabled) {
+      const proto = k.protocol !== undefined ? ` protocol=${k.protocol}` : '';
+      const ver = k.kernelVersion ? ` kernelVersion=${k.kernelVersion}` : '';
+      checks.push({ name: 'kernel', ok: true, detail: `rust (${k.bin})${proto}${ver}` });
+    } else if (k.reason) {
+      checks.push({ name: 'kernel', ok: false, detail: `BAD (${k.reason})` });
+    } else {
+      checks.push({ name: 'kernel', ok: true, detail: 'js fallback' });
+    }
   } catch (err) {
     const msg = err && err.message ? err.message : String(err);
     checks.push({ name: 'kernel', ok: false, detail: msg });
@@ -191,20 +199,24 @@ function cmdDoctor() {
   const gitVer = runCmd('git', ['--version']);
   checks.push({ name: 'git', ok: gitVer.ok, detail: gitVer.ok ? gitVer.stdout : gitVer.stderr });
 
-  const repoRoot = gitVer.ok ? git.getRepoRoot(projectRoot) : null;
-  checks.push({ name: 'repo', ok: !!repoRoot, detail: repoRoot ? repoRoot : 'not a git repo' });
-
-  if (repoRoot) {
-    let clean = false;
-    let detail = '';
+  if (gitVer.ok) {
+    let info = null;
     try {
-      clean = git.isClean(repoRoot);
-      detail = clean ? 'clean' : 'dirty';
+      info = git.getRepoInfo(projectRoot);
+      checks.push({
+        name: 'repo',
+        ok: !!info.repoRoot,
+        detail: info.repoRoot ? info.repoRoot : 'not a git repo'
+      });
+      if (info.repoRoot) {
+        checks.push({ name: 'clean', ok: !!info.clean, detail: info.clean ? 'clean' : 'dirty' });
+      }
     } catch (err) {
-      clean = false;
-      detail = err && err.message ? err.message : String(err);
+      const msg = err && err.message ? err.message : String(err);
+      checks.push({ name: 'repo', ok: false, detail: msg });
     }
-    checks.push({ name: 'clean', ok: clean, detail });
+  } else {
+    checks.push({ name: 'repo', ok: false, detail: 'git not available' });
   }
 
   const codex = runCmd('codex', ['--version']);
@@ -266,9 +278,9 @@ async function cmdPlan(args) {
   const runIdBase = requestedRunId || idMod.defaultRunId(intent);
   const runId = requestedRunId ? idMod.ensureUniqueRunId(projectRoot, requestedRunId) : idMod.ensureUniqueRunId(projectRoot, runIdBase);
 
-  const repoRoot = git.getRepoRoot(projectRoot);
-  const base = repoRoot
-    ? { repoRoot, branch: git.getCurrentBranch(repoRoot), sha: git.getHeadSha(repoRoot) }
+  const info = git.getRepoInfo(projectRoot);
+  const base = info.repoRoot
+    ? { repoRoot: info.repoRoot, branch: info.branch, sha: info.sha }
     : { repoRoot: projectRoot, branch: '', sha: '' };
 
   const { run } = runMod.initRun({
@@ -381,7 +393,8 @@ function cmdVerify(args) {
       );
     }
 
-    const repoRoot = git.getRepoRoot(projectRoot);
+    const info = git.getRepoInfo(projectRoot);
+    const repoRoot = info.repoRoot;
     if (!repoRoot) throw new Error('verify: requires a git repository');
 
     const wt = git.ensureWorktree({
@@ -427,9 +440,9 @@ async function cmdRun(args) {
   const runIdBase = requestedRunId || idMod.defaultRunId(intent);
   const runId = requestedRunId ? idMod.ensureUniqueRunId(projectRoot, requestedRunId) : idMod.ensureUniqueRunId(projectRoot, runIdBase);
 
-  const repoRoot = git.getRepoRoot(projectRoot);
-  const base = repoRoot
-    ? { repoRoot, branch: git.getCurrentBranch(repoRoot), sha: git.getHeadSha(repoRoot) }
+  const info = git.getRepoInfo(projectRoot);
+  const base = info.repoRoot
+    ? { repoRoot: info.repoRoot, branch: info.branch, sha: info.sha }
     : { repoRoot: projectRoot, branch: '', sha: '' };
 
   const { run } = runMod.initRun({