git:20260518.0a14b49 to git:20260520.dafaa1a

---

name: myco:runtime-environment-binary-management

description: |

Procedures for managing binary dispatch, runtime environment resolution, and machine-scoped coordination in Myco deployments. Covers layered runtime command resolution (~/.myco/runtime.command pins, project overrides, fallback chains), machine-scoped runtime architecture, binary masquerade detection and prevention, update coordination protocols, and Bun compilation deployment patterns. Use when setting up environments, troubleshooting binary dispatch issues, managing machine-scoped coordination, or implementing system updates, even if the user doesn't explicitly ask for runtime environment management.

managed_by: myco

user-invocable: true

allowed-tools: Read, Edit, Write, Bash, Grep, Glob

---

# Runtime Environment and Binary Management

Comprehensive procedures for managing Myco's binary dispatch system, runtime environment resolution, and machine-scoped coordination. These procedures ensure reliable binary execution, prevent environment conflicts, and maintain proper isolation across different deployment contexts in the Grove multi-project daemon architecture.

## Prerequisites

- Myco installation with proper symbiont structure

- Understanding of Myco's Grove multi-project daemon architecture (packages/myco/src/daemon/)

- Access to runtime configuration files (~/.myco/runtime.command, project-level configs)

- Familiarity with Bun compilation and single-file binary patterns

- Knowledge of Grove registration and project binding patterns

## Procedure A: Runtime Command Resolution and Fallback Management

```bash

cat ~/.myco/runtime.command

```

```bash

echo "/path/to/preferred/myco/binary" > ~/.myco/runtime.command

```

```bash

ls -la $(cat ~/.myco/runtime.command)

```

```bash

find .myco/ -name "runtime.command" -o -name "*.runtime.conf"

```

```bash

echo "/project/specific/myco/binary" > .myco/runtime.command

```

```bash

which myco

echo $PATH | tr ':' '\n' | grep myco

```

```bash

```

## Procedure B: Machine-Scoped Runtime Architecture

```bash

# Check daemon runtime source via API (Grove global daemon)

curl -s http://127.0.0.1:20915/api/stats | jq '.runtime'

```

```bash

ls -la ~/.myco/runtime.command

```

```bash

myco groves list # List all registered Groves

```

```bash

```

```bash

```

## Procedure C: Binary Masquerade Detection and Prevention

```bash

myco --version

which myco

file $(which myco) # Check if it's a compiled binary or script

```

```bash

realpath $(which myco)

ls -la $(dirname $(which myco))/myco*

```

```bash

strace -e execve myco --version 2>&1 | grep execve

```

```bash

myco doctor # Should report consistent binary paths

```

## Procedure D: Update Coordination and Environment Management

```bash

cp ~/.myco/runtime.command ~/.myco/runtime.command.backup

echo "/path/to/new/binary" > ~/.myco/runtime.command

myco --version # Verify new binary works

```

```bash

mv ~/.myco/runtime.command.backup ~/.myco/runtime.command

```

```bash

# After npm install -g @goondocks/myco@latest

# Restart Grove global daemon if versions don't match

myco daemon stop

myco daemon start

```

```bash

# Ensure Grove daemon serves JSON, not HTML after updates

curl -s http://127.0.0.1:20915/api/stats

# Should return JSON, not HTML error page

```

```bash

netstat -tuln | grep 20915

curl -s --connect-timeout 3 http://127.0.0.1:20915/api/stats || echo "Daemon wedged"

ps aux | grep myco | grep -v grep

```

```bash

# Get daemon PID holding port 20915

DAEMON_PID=$(lsof -ti:20915)

# Preserve daemon.json before killing process

cp ~/.myco/daemon.json ~/.myco/daemon.json.backup 2>/dev/null || true

kill -9 $DAEMON_PID

sleep 2

netstat -tuln | grep 20915 || echo "Port released"

```

```bash

myco daemon start

BINARY_VERSION=$(myco --version)

DAEMON_VERSION=$(curl -s http://127.0.0.1:20915/api/stats | jq -r '.version' 2>/dev/null)

if [ "$BINARY_VERSION" != "$DAEMON_VERSION" ]; then

echo "Version skew detected: binary=$BINARY_VERSION daemon=$DAEMON_VERSION"

echo "Restarting daemon to sync versions..."

myco daemon stop

myco daemon start

fi

```

```bash

# Restore daemon.json if it was corrupted during forced kill

if [ ! -s ~/.myco/daemon.json ] && [ -f ~/.myco/daemon.json.backup ]; then

cp ~/.myco/daemon.json.backup ~/.myco/daemon.json

echo "Restored daemon.json from backup"

fi

myco doctor # Should show no configuration errors

```

```bash

mv /new/myco/binary /usr/local/bin/myco.new

mv /usr/local/bin/myco.new /usr/local/bin/myco

```

```bash

myco doctor

ps aux | grep myco # Check running Grove daemon still works

```

## Procedure E: Bun Compilation and Deployment

```bash

cd packages/myco

npm run codegen

# This runs two generators:

# 1. scripts/gen-hook-config.ts → hook-config.generated.ts & manifests.generated.ts

# 2. scripts/gen-templates.mjs → templates.generated.ts

```

```javascript

const files = walk(TEMPLATES_DIR).sort();

const entries = files.map((abs) => {

const rel = path.relative(TEMPLATES_DIR, abs).split(path.sep).join('/');

const body = fs.readFileSync(abs, 'utf-8');

return [rel, body];

});

```

```typescript

// Generates both hook-config.generated.ts and manifests.generated.ts

// from src/hooks/ and src/symbionts/manifests/ respectively

```

```typescript

private readTemplateFile(relPath: string): string | null {

// Try filesystem first (development and testing)

const candidates = [

path.join(this.packageRoot, TEMPLATES_SUBDIR, relPath),

path.join(this.packageRoot, 'dist', TEMPLATES_SUBDIR, relPath),

];

for (const filePath of candidates) {

try { return fs.readFileSync(filePath, 'utf-8'); } catch { /* try next */ }

}

if (this.suppressBundledTemplates) return null;

const key = relPath.split(path.sep).join('/');

const bundled = BUNDLED_TEMPLATES[key];

return bundled !== undefined ? bundled : null;

}

private readManifestFile(relPath: string): ManifestData | null {

const bundled = BUNDLED_MANIFESTS[key];

return bundled !== undefined ? bundled : null;

}

```

```typescript

const template = installer.readTemplateFile('hook-guard.cjs');

const manifest = loader.readManifestFile('claude-code.json');

const template = installer.readTemplateFile('hook-guard.cjs');

const manifest = loader.readManifestFile('claude-code.json');

```

```typescript

export function resolvePackageRoot(): string {

// Try import.meta.dirname first — works in dev and old tsup layout

if (typeof import.meta.dirname === 'string' && !import.meta.dirname.includes('/$bunfs/')) {

return path.resolve(import.meta.dirname, '..', '..');

}

if (process.execPath && process.execPath !== process.argv0) {

return path.dirname(process.execPath);

}

return process.cwd();

}

```

```typescript

import libsqliteEmbed from '../../vendor-src/libsqlite3/darwin-arm64/libsqlite3.dylib' with { type: 'file' };

import vec0Embed from 'sqlite-vec-darwin-arm64/vec0.dylib' with { type: 'file' };

import ripgrepEmbed from '@vscode/ripgrep/bin/rg' with { type: 'file' };

await registerEmbeddedNativeDeps({

libsqliteEmbed, // Resolves to /$bunfs/path at runtime

ripgrepEmbed,

version: pkg.version,

});

```

```typescript

export async function registerEmbeddedNativeDeps(deps) {

const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'myco-'));

const libsqlitePath = path.join(tempDir, 'libsqlite3.dylib');

await fs.writeFile(libsqlitePath, await fs.readFile(deps.libsqliteEmbed));

process.env.MYCO_LIBSQLITE_PATH = libsqlitePath;

}

```

```bash

ls packages/myco/src/entries/

# cli.darwin-arm64.ts

# cli.darwin-x64.ts

# cli.linux-x64.ts

# cli.linux-arm64.ts

# cli.windows-x64.ts

# cli.js (shared logic)

```

```typescript

import libsqliteEmbed from '../../vendor-src/libsqlite3/darwin-arm64/libsqlite3.dylib' with { type: 'file' };

import libsqliteEmbed from '../../vendor-src/libsqlite3/linux-x64/libsqlite3.so' with { type: 'file' };

```

```bash

npm run build:binary

TARGET=darwin-arm64 npm run build:binary

TARGET=linux-x64 npm run build:binary

TARGET=windows-x64 npm run build:binary

npm run build:binaries

```

```javascript

const target = process.env.TARGET ?? detectHostTarget();

const entry = path.join(pkgRoot, 'src', 'entries', `cli.${target}.ts`);

const outputDir = path.join(pkgRoot, 'vendor', target);

const binaryName = target.startsWith('windows-') ? 'myco.exe' : 'myco';

const outfile = path.join(outputDir, binaryName);

const result = spawnSync(

'bun',

['build', '--compile', `--target=bun-${target}`, entry, '--outfile', outfile],

{ stdio: 'inherit', cwd: pkgRoot }

);

```

```bash

# Package structure: vendor-src/libsqlite3/{target}/libsqlite3.{ext}

packages/myco/vendor-src/libsqlite3/darwin-arm64/libsqlite3.dylib

packages/myco/vendor-src/libsqlite3/darwin-x64/libsqlite3.dylib

packages/myco/vendor-src/libsqlite3/linux-x64/libsqlite3.so

packages/myco/vendor-src/libsqlite3/linux-arm64/libsqlite3.so

packages/myco/vendor-src/libsqlite3/windows-x64/sqlite3.dll

```

```yaml

strategy:

matrix:

include:

- target: darwin-arm64

os: macos-latest

- target: linux-x64

os: ubuntu-latest

- target: windows-x64

os: windows-latest

steps:

run: |

TARGET=${{ matrix.target }} npm run build:binary

npm run build:verify

```

```javascript

let bin = 'myco'; // Default for global installs

try {

const aliasPath = path.resolve(__dirname, '..', '.myco', 'runtime.command');

const alias = fs.readFileSync(aliasPath, 'utf-8').trim();

try {

execFileSync(bin, process.argv.slice(2), { stdio: 'inherit' });

} catch (e) {

process.exit(e.status ?? 1);

}

```

```bash

```

```typescript

export function detectPathCollisions(binaryName: string): string[] {

const collisions: string[] = [];

const pathDirs = (process.env.PATH || '').split(path.delimiter);

for (const dir of pathDirs) {

const candidates = process.platform === 'win32'

? [`${binaryName}.exe`, `${binaryName}.cmd`, `${binaryName}.bat`]

: [binaryName];

for (const candidate of candidates) {

const binaryPath = path.join(dir, candidate);

if (fs.existsSync(binaryPath)) {

collisions.push(binaryPath);

}

}

}

return collisions;

}

```

```bash

# Check compiled binary structure using build scripts

cd packages/myco

node scripts/build-all-targets.mjs

file ./dist/myco-*

```

```bash

```

```bash

# Use the established build script for multi-target compilation

make build # Uses bun build --compile for all targets

ls -la ./dist/myco-*

```

```bash

file ./dist/myco-*

```

## Cross-Cutting Gotchas