fix(cross-platform): proper fixes for all 7 cross-platform issues

- fix(code): tree-sitter graceful fallback — `cleo code` commands check
  availability before running, exit with clear install instructions
  instead of crashing
- fix(cli): suppress ExperimentalWarning via process.emit filter in
  CLI entry point (replaces non-portable -S shebang flag)
- fix(crypto): Windows ACL verification via icacls for machine key
  (was completely skipped), set restrictive ACLs on key creation
- fix(agent): Windows SIGTERM graceful shutdown via `process.on('message')`
  for PM2 and other Windows process managers
- feat(code): isTreeSitterAvailable() exported for pre-flight checks

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: kryptobaseddev

packages/cleo/src/cli/commands/agent.ts

@@ -326,14 +326,20 @@ agent ${agentId}:
           { command: 'agent start' },
         );
 
-        // 6. Keep process alive until SIGINT/SIGTERM
+        // 6. Keep process alive until shutdown signal (cross-platform)
         const shutdown = () => {
           runtime.stop();
           void registry.update(agentId, { isActive: false }).catch(() => {});
           process.exit(0);
         };
         process.on('SIGINT', shutdown);
         process.on('SIGTERM', shutdown);
+        // Windows: listen for 'message' from parent process managers (PM2, etc.)
+        if (process.platform === 'win32') {
+          process.on('message', (msg) => {
+            if (msg === 'shutdown') shutdown();
+          });
+        }
 
         // Keep alive
         await new Promise(() => {});
@@ -780,6 +786,9 @@ agent ${agentId}:
         };
         process.on('SIGINT', shutdown);
         process.on('SIGTERM', shutdown);
+        if (process.platform === 'win32') {
+          process.on('message', (msg) => { if (msg === 'shutdown') shutdown(); });
+        }
         await new Promise(() => {});
       } catch (err) {
         cliOutput(
@@ -1057,6 +1066,9 @@ agent ${agentId}:
         };
         process.on('SIGINT', shutdown);
         process.on('SIGTERM', shutdown);
+        if (process.platform === 'win32') {
+          process.on('message', (msg) => { if (msg === 'shutdown') shutdown(); });
+        }
       } catch (err) {
         cliOutput(
           { success: false, error: { code: 'E_WATCH', message: String(err) } },

packages/cleo/src/cli/commands/code.ts

@@ -10,6 +10,21 @@
 
 import { defineCommand } from 'citty';
 
+/** Check tree-sitter availability before running code analysis. Exits with clear message if missing. */
+async function requireTreeSitter(): Promise<void> {
+  const { isTreeSitterAvailable } = await import('@cleocode/core/internal');
+  if (!isTreeSitterAvailable()) {
+    console.error(
+      'Error: tree-sitter is not installed. Code analysis features require tree-sitter grammar packages.\n\n' +
+        'Install with:\n' +
+        '  npm install -g tree-sitter-cli\n' +
+        '  # Or in the project: pnpm add tree-sitter-cli tree-sitter-typescript tree-sitter-javascript\n\n' +
+        'All other CLEO features work without tree-sitter. Only `cleo code` commands require it.',
+    );
+    process.exit(7); // exit code 7 = service unavailable
+  }
+}
+
 export const codeCommand = defineCommand({
   meta: { name: 'code', description: 'Code analysis via tree-sitter AST' },
   subCommands: {
@@ -19,6 +34,7 @@ export const codeCommand = defineCommand({
         file: { type: 'positional', description: 'Source file path', required: true },
       },
       async run({ args }) {
+        await requireTreeSitter();
         const { smartOutline } = await import('@cleocode/core/internal');
         const { join } = await import('node:path');
         const root = process.cwd();
@@ -52,6 +68,7 @@ export const codeCommand = defineCommand({
         path: { type: 'string', description: 'File pattern filter (e.g. src/**)' },
       },
       async run({ args }) {
+        await requireTreeSitter();
         const { smartSearch } = await import('@cleocode/core/internal');
         const root = process.cwd();
         const results = smartSearch(args.query, {
@@ -86,6 +103,7 @@ export const codeCommand = defineCommand({
         },
       },
       async run({ args }) {
+        await requireTreeSitter();
         const { smartUnfold } = await import('@cleocode/core/internal');
         const { join } = await import('node:path');
         const root = process.cwd();

packages/cleo/src/cli/index.ts

@@ -6,6 +6,17 @@
  * TODO: Migrate all 89 commands to native citty pattern (epic T5730)
  */
 
+// Suppress ExperimentalWarning from node:sqlite and other experimental APIs.
+// This replaces the non-portable `#!/usr/bin/env -S node --disable-warning=ExperimentalWarning` shebang.
+const originalEmit = process.emit.bind(process);
+// @ts-expect-error -- overriding process.emit to filter warnings
+process.emit = function (event: string, ...args: unknown[]) {
+  if (event === 'warning' && args[0] && (args[0] as { name?: string }).name === 'ExperimentalWarning') {
+    return false;
+  }
+  return originalEmit(event, ...args);
+};
+
 import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';

packages/core/src/code/parser.ts

@@ -24,16 +24,46 @@ import { detectLanguage, type TreeSitterLanguage } from '../lib/tree-sitter-lang
 // Tree-sitter CLI resolution
 // ---------------------------------------------------------------------------
 
+/** Whether tree-sitter is available on this system. */
+let _treeSitterAvailable: boolean | null = null;
+
+/** Check if tree-sitter CLI is available. Cached after first call. */
+export function isTreeSitterAvailable(): boolean {
+  if (_treeSitterAvailable !== null) return _treeSitterAvailable;
+  try {
+    resolveTreeSitterBin();
+    _treeSitterAvailable = true;
+  } catch {
+    _treeSitterAvailable = false;
+  }
+  return _treeSitterAvailable;
+}
+
 /** Resolve the tree-sitter CLI binary from node_modules. */
 function resolveTreeSitterBin(): string {
+  // Also check platform-specific binary extension for Windows
+  const ext = process.platform === 'win32' ? '.exe' : '';
+  const binName = `tree-sitter${ext}`;
   const candidates = [
-    join(process.cwd(), 'packages', 'core', 'node_modules', '.bin', 'tree-sitter'),
-    join(process.cwd(), 'node_modules', '.bin', 'tree-sitter'),
+    join(process.cwd(), 'packages', 'core', 'node_modules', '.bin', binName),
+    join(process.cwd(), 'node_modules', '.bin', binName),
+    // npm global install paths
+    join(process.cwd(), 'node_modules', 'tree-sitter-cli', binName),
   ];
+  // Also try without extension (npm .cmd shim on Windows)
+  if (ext) {
+    candidates.push(
+      join(process.cwd(), 'packages', 'core', 'node_modules', '.bin', 'tree-sitter'),
+      join(process.cwd(), 'node_modules', '.bin', 'tree-sitter'),
+    );
+  }
   for (const p of candidates) {
     if (existsSync(p)) return p;
   }
-  throw new Error('tree-sitter CLI not found. Run: pnpm add -F @cleocode/core tree-sitter-cli');
+  throw new Error(
+    'tree-sitter CLI not found. Code analysis features (cleo code outline/search/unfold) ' +
+      'require tree-sitter. Install with: npm install tree-sitter-cli',
+  );
 }
 
 // ---------------------------------------------------------------------------

packages/core/src/crypto/credentials.ts

@@ -16,6 +16,7 @@
  */
 
 import { createCipheriv, createDecipheriv, createHmac, randomBytes } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
 import { chmod, mkdir, readFile, stat, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 
@@ -63,9 +64,24 @@ async function getMachineKey(): Promise<Buffer> {
   const keyPath = getMachineKeyPath();
 
   try {
-    // Check existing key — skip permission check on Windows (NTFS doesn't support Unix modes)
+    // Verify key file permissions
     const stats = await stat(keyPath);
-    if (process.platform !== 'win32') {
+    if (process.platform === 'win32') {
+      // Windows: use icacls to verify the key is not world-readable.
+      try {
+        const output = execFileSync('icacls', [keyPath], { encoding: 'utf-8', timeout: 5000 });
+        const unsafePatterns = /\\(Users|Everyone|Authenticated Users):/i;
+        if (unsafePatterns.test(output)) {
+          throw new Error(
+            `Machine key has unsafe Windows ACLs (accessible to other users). ` +
+              `Fix with: icacls "${keyPath}" /inheritance:r /grant:r "%USERNAME%":F`,
+          );
+        }
+      } catch (aclErr) {
+        if (aclErr instanceof Error && aclErr.message.includes('unsafe')) throw aclErr;
+      }
+    } else {
+      // Unix: verify 0600 permissions
       const mode = stats.mode & 0o777;
       if (mode !== 0o600) {
         throw new Error(
@@ -89,7 +105,16 @@ async function getMachineKey(): Promise<Buffer> {
       const key = randomBytes(KEY_LENGTH);
       await mkdir(dirname(keyPath), { recursive: true });
       await writeFile(keyPath, key, { mode: 0o600 });
-      await chmod(keyPath, 0o600); // Ensure perms even on existing dirs
+      if (process.platform === 'win32') {
+        // Lock down Windows ACLs: remove inherited permissions, grant only current user
+        try {
+          execFileSync('icacls', [keyPath, '/inheritance:r', '/grant:r', `${process.env['USERNAME'] ?? 'CURRENT_USER'}:F`], { timeout: 5000 });
+        } catch {
+          // Best-effort — icacls may not be available in all environments
+        }
+      } else {
+        await chmod(keyPath, 0o600);
+      }
       return key;
     }
     throw err;

packages/core/src/internal.ts

@@ -44,7 +44,7 @@ export {
 } from './bootstrap.js';
 export { smartOutline } from './code/outline.js';
 // Code analysis (Smart Explore)
-export { batchParse, parseFile } from './code/parser.js';
+export { batchParse, isTreeSitterAvailable, parseFile } from './code/parser.js';
 export { smartSearch } from './code/search.js';
 export { smartUnfold } from './code/unfold.js';
 export type { ViolationLogEntry } from './compliance/protocol-enforcement.js';