Isolation & Git Conventions

Branded Types (packages/git/src/types.ts)

Always use the branded constructors — they reject empty strings at runtime and prevent passing the wrong string type:

import { toRepoPath, toBranchName, toWorktreePath } from '@archon/git';
import type { RepoPath, BranchName, WorktreePath } from '@archon/git';

const repo = toRepoPath('/home/user/owner/repo');    // RepoPath
const branch = toBranchName('feature-auth');          // BranchName
const wt = toWorktreePath('/home/.archon/worktrees/x'); // WorktreePath

Git operations return GitResult<T> discriminated union: \{ ok: true; value: T \} or \{ ok: false; error: GitError \}. Always check .ok before accessing .value.

IsolationResolver — 7-Step Resolution Order

1. Existing env — use existingEnvId if worktree still exists on disk
2. No codebase — skip isolation entirely, return status: 'none'
3. Workflow reuse — find active env with same (codebaseId, workflowType, workflowId)
4. Linked issue sharing — PR can reuse the worktree from a linked issue
5. PR branch adoption — find existing worktree by branch name (findWorktreeByBranch)
6. Limit check + auto-cleanup — if at maxWorktrees (default 25), try makeRoom() first
7. Create new — call provider.create(isolationRequest) then store.create()

If store.create() fails after provider.create() succeeds, the orphaned worktree is cleaned up best-effort before re-throwing.

Error Handling Pattern

import { classifyIsolationError, isKnownIsolationError } from '@archon/isolation';

try {
  await provider.create(request);
} catch (error) {
  const err = error instanceof Error ? error : new Error(String(error));
  if (!isKnownIsolationError(err)) {
    throw err; // Unknown = programming bug, propagate as crash
  }
  const userMessage = classifyIsolationError(err); // Maps to friendly message
  // ...send userMessage to platform, return blocked resolution
}

Known error patterns: permission denied, eacces, timeout, no space left, enospc, not a git repository, branch not found.

IsolationBlockedError signals ALL message handling should stop — the user has already been notified.

Git Safety Rules

• NEVER run git clean -fd — permanently deletes untracked files. Use git checkout . instead.
• Always use execFileAsync (from @archon/git/exec), never exec or execSync
• hasUncommittedChanges() returns true on unexpected errors (conservative — prevents data loss)
• Worktree paths follow project-scoped layout: ~/.archon/workspaces/\{owner\}/\{repo\}/worktrees/\{branch\}

Architecture

• @archon/git — zero @archon/* dependencies; only branded types and execFileAsync wrapper
• @archon/isolation — depends only on @archon/git + @archon/paths
• IIsolationStore interface injected into IsolationResolver — never call DB directly from git package
• IIsolationProvider interface — WorktreeProvider is the only implementation
• Stale env cleanup is best-effort: markDestroyedBestEffort() logs errors but never throws

Anti-patterns

• Never call git via exec() or shell string — always execFileAsync('git', [...args])
• Never treat IsolationBlockedError as recoverable — it means user was notified, stop processing
• Never use a plain string where RepoPath / BranchName / WorktreePath is expected
• Never skip the isKnownIsolationError() check — unknown errors must propagate as crashes