git:20260613.ad8665d to git:20260629.2978c18

- MYCO_SERVICE_VARIANT=dev \

- packages/myco-darwin-arm64/bin/myco doctor

- **Solution:** The global launcher uses a **dev-build detection chain** to determine whether the running binary is a development build or production, then routes to the appropriate daemon instance.

- ### The Dogfooding Route Chain

- ```typescript

- // In ~/.myco/launcher.c (global hook bootstrap)

- // Step 1: Hook fires from inside the myco project (e.g., Claude Code)

- // Step 2: Global launcher dispatches to the appropriate daemon

- // Step 3: Daemon identity is determined by detectDevBuild() check

- export function selectDaemonForInvocation(): {

- daemonServicePath: string;

- runtimeCommandPath: string;

- } {

- // Pattern: detectDevBuild() checks if current binary is dev or production

- const isDevBuild = detectDevBuild();

-

- if (isDevBuild) {

- // Development: use machine-scoped dev daemon

- // ~/.myco/service-dev/ contains daemon.json for development instance

- return {

- daemonServicePath: path.join(os.homedir(), '.myco', 'service-dev', 'daemon.json'),

- runtimeCommandPath: path.join(os.homedir(), '.myco', 'runtime.command')

- };

- } else {

- // Production: use standard service daemon

- // ~/.myco/service/ contains daemon.json for production instance

- return {

- daemonServicePath: path.join(os.homedir(), '.myco', 'service', 'daemon.json'),

- runtimeCommandPath: path.join(os.homedir(), '.myco', 'runtime.command')

- };

- }

- }

- // Dev-build detection chain

- export function detectDevBuild(): boolean {

- // Priority 1: Check if running inside git worktree with compiled binary

- const gitDir = findNearestGitDir();

- const worktreeMarker = path.join(gitDir, '.git', 'worktrees');

-

- // Priority 2: Check for vendor-src directory (dev artifact not in production binary)

- const vendorSrcDir = path.join(process.execPath, '..', 'vendor-src');

- if (fs.existsSync(vendorSrcDir)) {

- return true;

- }

-

- // Priority 3: Check for uncompiled source markers in execution path

- const sourceMarkers = ['src/', 'packages/myco/src', 'tsconfig.json'];

- const execDir = path.dirname(process.execPath);

- for (const marker of sourceMarkers) {

- if (execDir.includes(marker)) return true;

- }

-

- // Default: assume production

- return false;

- }

- ```

- ### Machine-Scoped Service Selection Pattern

- ```typescript

- // In packages/myco/src/grove/paths.ts

- export class ServicePaths {

- /**

- * Production service daemon lives at ~/.myco/service/daemon.json

- * Development service daemon lives at ~/.myco/service-dev/daemon.json

- *

- * The selection happens once at process startup (after detectDevBuild())

- * and is immutable per process instance.

- */

- private static selectedServiceDir: string | null = null;

-

- static selectServiceDirectory(): string {

- if (ServicePaths.selectedServiceDir !== null) {

- return ServicePaths.selectedServiceDir;

- }

-

- // Determine at startup (after detectDevBuild())

- const isDev = detectDevBuild();

- const baseDir = path.join(os.homedir(), '.myco');

-

- ServicePaths.selectedServiceDir = isDev

- ? path.join(baseDir, 'service-dev')

- : path.join(baseDir, 'service');

-

- return ServicePaths.selectedServiceDir;

- }

-

- static getDaemonJsonPath(): string {

- return path.join(ServicePaths.selectServiceDirectory(), 'daemon.json');

- }

- }

- // Usage in daemon startup

- export async function loadDaemonIdentity(): Promise<DaemonRecord> {

- const daemonJsonPath = ServicePaths.getDaemonJsonPath();

- const content = await fs.promises.readFile(daemonJsonPath, 'utf-8');

- return JSON.parse(content);

- }

- ```

- ### Gotchas in Dogfood Routing

- **Stale hook gotcha:** Hooks installed globally may be outdated if Myco binary is updated. Ensure global hooks are regenerated on production upgrade and again on dev-build downgrades.

- **Dev-only service directory:** Contributors running dev builds must ensure `~/.myco/service-dev/` exists and is owned by the development daemon, not the production service.

- ### Global Beta Channel Workflow

-

- #### User Initiates Beta Join

-

- ```bash

- # User runs command to switch to beta channel

- myco install:beta

-

- # Internally, this invokes the global upgrade path:

- # 1. Download beta-tagged release from artifact store

- # 2. Verify checksum matches expected beta build

- # 3. Stop running service daemon (if any)

- # 4. Replace global Myco binary with beta build

- # 5. Restart daemon to load new binary

- ```

-

- #### Implementation Pattern

-

- ```typescript

- // In packages/myco/src/cli/install.ts (or daemon API endpoint)

- export async function switchToBetaChannel(): Promise<{ success: boolean; message: string }> {

- // Step 1: Fetch beta release metadata

- const betaRelease = await fetchBetaReleaseMetadata();

- if (!betaRelease) {

- throw new Error('No beta release available');

- }

-

- // Step 2: Download beta artifact

- const betaPath = await downloadBinaryRelease(betaRelease.downloadUrl, {

- checksumExpected: betaRelease.sha256,

- tempDir: path.join(os.homedir(), '.myco', 'tmp')

- });

-

- // Step 3: Stop production daemon before binary replacement

- // Use graceful shutdown with timeout (critical to avoid ETXTBSY on Windows)

- await stopDaemonWithTimeout({ timeoutMs: 30000 });

-

- // Step 4: Global replacement - swap binary atomically

- const globalBinPath = path.join(os.homedir(), '.myco', 'bin', 'myco');

- const backupPath = path.join(os.homedir(), '.myco', 'bin', 'myco.production');

-

- await fsAtomicReplace(globalBinPath, betaPath, {

- backupPath, // Save production binary for rollback

- mode: 0o755

- });

-

- // Step 5: Restart daemon with new beta binary

- // Service daemon will auto-restart via systemd/launchd

- await startDaemon({

- waitForHealthy: true,

- timeoutMs: 30000

- });

-

- return {

- success: true,

- message: `Switched to beta channel. Running ${betaRelease.version}`

- };

- }

-

- // Atomic replacement with backup pattern

- async function fsAtomicReplace(

- targetPath: string,

- sourcePath: string,

- opts: { backupPath: string; mode: number }

- ): Promise<void> {

- // Pattern: Backup original, move new to target, verify

-

- if (fs.existsSync(targetPath)) {

- await fs.promises.rename(targetPath, opts.backupPath);

- }

-

- try {

- await fs.promises.copyFile(sourcePath, targetPath);

- await fs.promises.chmod(targetPath, opts.mode);

-

- // Verify new binary is executable

- const isExecutable = await isFileExecutable(targetPath);

- if (!isExecutable) {

- throw new Error(`New binary not executable: ${targetPath}`);

- }

- } catch (err) {

- // Rollback to backup on failure

- if (fs.existsSync(opts.backupPath)) {

- await fs.promises.rename(opts.backupPath, targetPath);

- }

- throw err;

- }

- }

- ```

-

- ### Beta Channel Rollback Pattern

- ```typescript

- export async function rollbackBetaToPrevious(): Promise<{ success: boolean; version: string }> {

- const backupPath = path.join(os.homedir(), '.myco', 'bin', 'myco.production');

- const globalBinPath = path.join(os.homedir(), '.myco', 'bin', 'myco');

- if (!fs.existsSync(backupPath)) {

- throw new Error('No production backup available for rollback');

- }

- // Stop daemon before rollback

- await stopDaemonWithTimeout({ timeoutMs: 30000 });

- // Restore production binary

- await fs.promises.rename(backupPath, globalBinPath);

- await fs.promises.chmod(globalBinPath, 0o755);

- // Restart with production binary

- await startDaemon({ waitForHealthy: true });

- // Verify version

- const versionOutput = await execSync('myco --version');

- return {

- success: true,

- version: parseVersionFromOutput(versionOutput)

- };

- }

- ```typescript

- // In ~/.myco/myco.yaml

- export interface BetaChannelState {

- enabled: boolean;

- currentRelease: string; // e.g., "2.15.0-beta.2"

- productionBackupPath: string; // Path to production binary backup

- switchedAt: number; // Unix timestamp

- canRollback: boolean;

- }

-

- // Query current channel

- export async function getCurrentChannel(): Promise<'production' | 'beta'> {

- const config = await loadConfig();

- return config.beta?.enabled ? 'beta' : 'production';

- }

- ```

- **Daemon restart timing gotcha:** On macOS/Linux, the service daemon may be lingering from the old binary. Use `launchctl unload` or `systemctl stop` before binary replacement to avoid ETXTBSY ("text file busy") errors.

- **Backup path gotcha:** The backup production binary must be saved before replacement and stored outside the executable location to prevent accidental cleanup. Use `~/.myco/bin/myco.production` as the canonical backup location.

- **Checksum verification gotcha:** Always verify the beta release checksum before performing binary replacement. Use SHA-256 hashes published alongside the release.

- const { execFileSync } = require('child_process');

- // CRITICAL: Quote the binary path to handle spaces

- // WRONG: Binary path with spaces will be split into multiple args

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

-

- // RIGHT: Use shell quoting for binary paths with spaces

- const { spawnSync } = require('child_process');

- #### Worktree Vendor Assets and Path Resolution

-

- **Issue**: When Myco is run from a git worktree with development assets, the runtime.command binary must correctly locate and load vendor assets (libsqlite3, sqlite-vec, ripgrep) from the development binary's directory.

-

- ```typescript

- // In src/runtime/resolve-package.ts (package root discovery for worktree)

- export function resolvePackageRoot(): string {

- // Pattern: Try import.meta.dirname first (works in dev and compiled),

- // then fallback to process.execPath (for compiled binaries),

- // then process.cwd() (last resort)

-

- // 1. Development: import.meta.dirname points to source directory

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

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

- }

-

- // 2. Compiled binary: process.execPath points to binary location

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

- return path.dirname(process.execPath);

- }

-

- // 3. Last resort: working directory (may not have vendor assets)

- return process.cwd();

- }

-

- // In src/daemon/main.ts (vendor asset loading for global operation)

- export async function loadVendorAssets() {

- const pkgRoot = resolvePackageRoot();

- const vendorDir = path.join(pkgRoot, 'vendor-src');

-

- // Load embedded native dependencies from vendor directory

- const libsqlitePath = path.join(vendorDir, 'libsqlite3', 'darwin-arm64', 'libsqlite3.dylib');

- process.env.MYCO_LIBSQLITE_PATH = libsqlitePath;

-

- // Verify vendor assets exist (critical for global deployment)

- if (!fs.existsSync(libsqlitePath)) {

- throw new Error(`Vendor asset not found: ${libsqlitePath}`);

- }

- }

- ```

-

- **Worktree vendor asset loading**: When running development binaries from git worktrees, the package resolution must correctly locate vendor assets. Use resolvePackageRoot() with import.meta.dirname detection to find assets; don't rely on process.cwd() which may be in a different project entirely.

- **Service directory isolation**: Dev and production service daemons must use separate directories (~/.myco/service-dev/ and ~/.myco/service/) to prevent state conflicts. The service directory selection happens once at process startup and is immutable for that instance.

- **Beta channel backup safeguard**: Always keep a backup of the production binary before beta channel switching. The backup path (~/.myco/bin/myco.production) must be outside normal executable locations to prevent accidental deletion or overwriting.

- **`~/.myco/logs/launcher.log` is the first hook failure diagnostic:** The global launcher (`packages/myco/src/symbionts/templates/_shared/global-launcher.cjs`) appends a timestamped one-line record to `~/.myco/logs/launcher.log` on every launch failure — signal kills, `ENOENT`, path-resolution errors, binary exec errors. Check this file before inspecting daemon logs when hooks silently fail to fire. The launcher never throws on log-write failure, so absence of the file means zero hook launch failures (not a broken log path).

- **Detached update installer rewrites hooks synchronously before daemon restart:** `packages/myco/src/daemon/update-installer.ts` generates a shell script that is spawned detached from the daemon (stdio ignored, unreffed so the parent exits immediately). Within the script, npm installation and hook/plugin file rewriting happen synchronously before the daemon respawn — ensuring hooks and daemon always co-ship at the updated version. This is the source of the no-protocol-skew guarantee in capture hooks.