agent-takkub 1.6.21 → 1.6.23

package/npm/bin/agent-takkub.js

@@ -4,7 +4,7 @@
 const { spawnSync } = require('child_process');
 const {
   venvPythonIfExists,
-  pythonLooksExecutable,
+  pythonExecutableProblem,
   brokenInterpreterMessage,
   agentTakkubHome,
 } = require('../scripts/lib');
@@ -14,8 +14,9 @@ if (!py) {
   console.error('agent-takkub is not provisioned. Run: npm install -g agent-takkub');
   process.exit(1);
 }
-if (!pythonLooksExecutable(py)) {
-  console.error(brokenInterpreterMessage(py, agentTakkubHome()));
+const problem = pythonExecutableProblem(py);
+if (problem) {
+  console.error(brokenInterpreterMessage(py, agentTakkubHome(), problem));
   process.exit(1);
 }
 const r = spawnSync(py, ['-m', 'agent_takkub', ...process.argv.slice(2)], { stdio: 'inherit' });

package/npm/bin/takkub.js

@@ -4,7 +4,7 @@
 const { spawnSync } = require('child_process');
 const {
   venvPythonIfExists,
-  pythonLooksExecutable,
+  pythonExecutableProblem,
   brokenInterpreterMessage,
   agentTakkubHome,
 } = require('../scripts/lib');
@@ -14,8 +14,9 @@ if (!py) {
   console.error('takkub is not provisioned. Run: npm install -g agent-takkub');
   process.exit(1);
 }
-if (!pythonLooksExecutable(py)) {
-  console.error(brokenInterpreterMessage(py, agentTakkubHome()));
+const problem = pythonExecutableProblem(py);
+if (problem) {
+  console.error(brokenInterpreterMessage(py, agentTakkubHome(), problem));
   process.exit(1);
 }
 const r = spawnSync(py, ['-m', 'agent_takkub.cli', ...process.argv.slice(2)], { stdio: 'inherit' });

package/npm/scripts/lib.js

@@ -53,41 +53,84 @@ function findWheelForVersion(distDir, version) {
 // header bytes, no attempt to execute the file) so a broken interpreter is
 // never spawned at all — spawning it is exactly the risky step that can
 // leave the file locked/hard to overwrite during recovery.
-const MIN_PYTHON_EXE_BYTES = 40 * 1024; // a real venv python.exe/python is comfortably >90KB
+//
+// The floor only needs to catch truncation (#341's 29-byte case), not judge
+// what a "normal-sized" interpreter looks like — a pyenv/python.org
+// framework build's `bin/pythonX.Y` is a tiny Mach-O stub that re-execs into
+// Python.framework and can be well under 40KB while still being completely
+// runnable (#446). Magic-byte sniffing is what actually distinguishes it
+// from garbage; size only rules out an empty/near-empty file.
+const MIN_PYTHON_EXE_BYTES = 1024;
+
+const ELF_MAGIC = 0x7f454c46; // '\x7fELF', big-endian read of the 4 header bytes
+const MACHO_MAGICS = new Set([
+  0xfeedface, // MH_MAGIC (32-bit)
+  0xcefaedfe, // MH_CIGAM (32-bit, byte-swapped)
+  0xfeedfacf, // MH_MAGIC_64
+  0xcffaedfe, // MH_CIGAM_64 (byte-swapped)
+  0xcafebabe, // FAT_MAGIC (universal/fat binary)
+  0xbebafeca, // FAT_CIGAM (universal/fat binary, byte-swapped)
+]);
 
 // Opens the path exactly once and stats/reads that same descriptor for the
 // rest of the check — never stat a path and then separately open it, which
 // leaves a window for the file at that name to change between the two
 // syscalls (CodeQL js/file-system-race, alert #29).
-function pythonLooksExecutable(py) {
+//
+// Returns null when `py` looks like a real, runnable interpreter, otherwise
+// a short machine-readable reason so callers can explain what specifically
+// failed instead of a single opaque "not a real executable".
+function pythonExecutableProblem(py) {
   let fd;
   try {
     fd = fs.openSync(py, 'r');
   } catch (_e) {
-    return false;
+    return 'missing';
   }
   try {
     const stat = fs.fstatSync(fd);
-    if (!stat.isFile() || stat.size < MIN_PYTHON_EXE_BYTES) return false;
+    if (!stat.isFile()) return 'not-a-file';
+    if (stat.size < MIN_PYTHON_EXE_BYTES) return 'too-small';
+    const buf = Buffer.alloc(4);
+    const n = fs.readSync(fd, buf, 0, 4, 0);
     if (process.platform === 'win32') {
       // Windows PE executables always start with the 'MZ' DOS-header magic.
-      const buf = Buffer.alloc(2);
-      fs.readSync(fd, buf, 0, 2, 0);
-      return buf[0] === 0x4d && buf[1] === 0x5a; // 'M', 'Z'
+      return n >= 2 && buf[0] === 0x4d && buf[1] === 0x5a ? null : 'bad-magic';
     }
-    return true;
+    // POSIX: accept a real ELF or Mach-O binary, or a shebang script — a
+    // pyenv shim / venv `python` wrapper is a text file starting with `#!`,
+    // not a compiled executable, and is just as valid an interpreter path.
+    if (n >= 2 && buf[0] === 0x23 && buf[1] === 0x21) return null; // '#!'
+    if (n < 4) return 'bad-magic';
+    const magic = buf.readUInt32BE(0);
+    if (magic === ELF_MAGIC || MACHO_MAGICS.has(magic)) return null;
+    return 'bad-magic';
   } catch (_e) {
-    return false;
+    return 'read-error';
   } finally {
     fs.closeSync(fd);
   }
 }
 
-function brokenInterpreterMessage(py, home) {
+function pythonLooksExecutable(py) {
+  return pythonExecutableProblem(py) === null;
+}
+
+const PROBLEM_DESCRIPTIONS = {
+  missing: "the file doesn't exist",
+  'not-a-file': 'the path exists but is not a regular file (e.g. a directory)',
+  'too-small': `the file is smaller than ${MIN_PYTHON_EXE_BYTES} bytes — too small to be a real interpreter`,
+  'bad-magic': "the file's header does not match a known executable format (PE/ELF/Mach-O) or a shebang script",
+  'read-error': 'the file could not be read to check its header',
+};
+
+function brokenInterpreterMessage(py, home, problem) {
   const venvDirPath = path.join(home, 'venv');
+  const why = PROBLEM_DESCRIPTIONS[problem] || PROBLEM_DESCRIPTIONS['bad-magic'];
   return (
     `[agent-takkub] the cockpit interpreter looks broken (exists but is not a real executable):\n` +
     `    ${py}\n` +
+    `    Reason: ${why}.\n` +
     '    Something outside agent-takkub overwrote or truncated this file — the cockpit\n' +
     '    did not do this to itself. Fix:\n' +
     '      1) close every running cockpit/takkub window and process for this install\n' +
@@ -116,5 +159,6 @@ module.exports = {
   venvPythonw,
   findWheelForVersion,
   pythonLooksExecutable,
+  pythonExecutableProblem,
   brokenInterpreterMessage,
 };

package/package.json

@@ -1,50 +1,50 @@
-{
-  "name": "agent-takkub",
-  "version": "1.6.21",
-  "description": "Desktop cockpit for orchestrating a team of Claude Code agents (Windows + macOS). Install globally: npm i -g agent-takkub",
-  "keywords": [
-    "claude",
-    "claude-code",
-    "ai-agents",
-    "agent-orchestration",
-    "cockpit",
-    "desktop",
-    "cli",
-    "developer-tools"
-  ],
-  "author": "takkub",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/takkub/agent-takkub.git"
-  },
-  "homepage": "https://github.com/takkub/agent-takkub#readme",
-  "bugs": {
-    "url": "https://github.com/takkub/agent-takkub/issues"
-  },
-  "bin": {
-    "agent-takkub": "npm/bin/agent-takkub.js",
-    "takkub": "npm/bin/takkub.js"
-  },
-  "scripts": {
-    "postinstall": "node npm/scripts/postinstall.js",
-    "prepublishOnly": "node npm/scripts/preflight-publish.js",
-    "test": "node --test npm/scripts/*.test.js"
-  },
-  "files": [
-    "npm/",
-    "!npm/scripts/*.test.js",
-    "dist/*.whl",
-    "assets/icon.ico",
-    "assets/icon.png",
-    "assets/cockpit-main.png"
-  ],
-  "os": [
-    "win32",
-    "darwin"
-  ],
-  "engines": {
-    "node": ">=18"
-  },
-  "engines-note": "This floor is for agent-takkub itself. The OPTIONAL graft code-intelligence feature (installed separately via `takkub doctor --fix`, not an npm dependency of this package) needs Node >=20 — see README's Requirements section. Not raised here because it would force the >=20 floor onto every user even though graft stays off until explicitly enabled.",
-  "license": "MIT"
-}
+{
+  "name": "agent-takkub",
+  "version": "1.6.23",
+  "description": "Desktop cockpit for orchestrating a team of Claude Code agents (Windows + macOS). Install globally: npm i -g agent-takkub",
+  "keywords": [
+    "claude",
+    "claude-code",
+    "ai-agents",
+    "agent-orchestration",
+    "cockpit",
+    "desktop",
+    "cli",
+    "developer-tools"
+  ],
+  "author": "takkub",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/takkub/agent-takkub.git"
+  },
+  "homepage": "https://github.com/takkub/agent-takkub#readme",
+  "bugs": {
+    "url": "https://github.com/takkub/agent-takkub/issues"
+  },
+  "bin": {
+    "agent-takkub": "npm/bin/agent-takkub.js",
+    "takkub": "npm/bin/takkub.js"
+  },
+  "scripts": {
+    "postinstall": "node npm/scripts/postinstall.js",
+    "prepublishOnly": "node npm/scripts/preflight-publish.js",
+    "test": "node --test npm/scripts/*.test.js"
+  },
+  "files": [
+    "npm/",
+    "!npm/scripts/*.test.js",
+    "dist/*.whl",
+    "assets/icon.ico",
+    "assets/icon.png",
+    "assets/cockpit-main.png"
+  ],
+  "os": [
+    "win32",
+    "darwin"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "engines-note": "This floor is for agent-takkub itself. The OPTIONAL graft code-intelligence feature (installed separately via `takkub doctor --fix`, not an npm dependency of this package) needs Node >=20 — see README's Requirements section. Not raised here because it would force the >=20 floor onto every user even though graft stays off until explicitly enabled.",
+  "license": "MIT"
+}