How Apache Maka Uses Isolated Git Worktrees in Its Graph Implementation for Safe Source Project Execution

Apache Maka's Graph orchestration provisions dedicated Git worktrees to provide each sub-agent with an isolated, writable filesystem view of source projects, ensuring safe concurrent execution through deterministic worktree allocation, path validation, and automated lifecycle management.

Apache Maka is an open-source framework for orchestrating complex agent workflows. Its Graph implementation manages child (sub-agent) sessions that require independent access to source code repositories. To prevent workspace conflicts and ensure reproducible execution, the runtime leverages isolated Git worktrees managed by the GitWorktreeChildExecutor component. This architecture allows multiple sub-agents to operate on the same repository simultaneously without interfering with the host repository's state or each other's working directories.

Worktree Allocation During Host Initialization

The isolation strategy begins when the runtime host initializes. In packages/runtime-host/src/server/execution-composition.ts (lines 97-99), the system instantiates a GitWorktreeChildExecutor that points to a dedicated storage directory under the host's root path, typically located under subagent-worktrees/.

const worktreeChildExecutor = createGitWorktreeChildExecutor({
  storageRoot: context.owner.capability.canonicalPath,
});

This executor serves as the factory for all sub-agent worktrees, ensuring that every isolated workspace remains within the host-owned filesystem boundary and can be tracked throughout the graph execution lifecycle.

Provisioning Deterministic Worktrees for Sub-Agents

When the Graph coordinator requests a workspace for a sub-agent, the executor provisions a worktree with a deterministic path derived from the lease ID. Implemented in packages/storage/src/git-worktree-child-executor.ts (lines 46-59 and 246-259), the provisioning logic either reuses an existing worktree or creates a new one by executing native Git commands:

const worktreePath = join(root, suffix);
await runGit(sourceWorktreeRoot, ['worktree', 'add', '--quiet', worktreePath, branch]);
await runGit(worktreePath, ['switch', '--quiet', '-c', branch]);

The deterministic naming convention (subagent_worktree_<hash>) ensures that lease-to-worktree mappings remain consistent across session recoveries and retries, while the unique branch-per-worktree model prevents Git object contamination.

Enforcing Isolation Boundaries

To prevent cross-contamination between sub-agents or host escape vulnerabilities, the executor validates worktree ownership through the inspectOwnedWorktree method. As implemented in packages/storage/src/git-worktree-child-executor.ts (lines 36-39), the system throws an error if a worktree resolves outside its designated host-owned path:

if (worktreePath !== normalize(path)) {
  throw new Error(`Subagent workspace resolves outside its Host-owned path: ${path}`);
}

This validation ensures that each worktree's Git common directory remains linked to the host repository, maintaining the security boundary required for safe graph execution while preventing accidental access to sensitive host filesystem locations.

Graph Coordination and Patch Capture

The AgentGraphCoordinator (instantiated via packages/runtime/stream-graph-coordinator.ts) leverages the worktree executor to manage workspace state transitions during graph traversal. During sub-agent execution, the system captures changes as patches that can be safely merged back into the main workflow or passed to subsequent graph nodes.

In packages/runtime/src/session-manager.ts (lines 1050-1056), the runtime captures workspace diffs only after ensuring a quiescent state:

await this.deps.worktreeChildExecutor!.capturePatch(binding);

This mechanism allows the Graph implementation to treat isolated worktrees as ephemeral execution environments while preserving the resulting changes for downstream processing without exposing the host workspace to intermediate file states.

Worktree Lifecycle Management

The executor manages worktree retirement through explicit cleanup operations. When a sub-agent session ends or is recovered, the system either removes the worktree entirely or prepares it for reuse by the next lease holder. The removeOwnedWorktree method in packages/storage/src/git-worktree-child-executor.ts (lines 88-100) handles branch deletion and directory cleanup:

await this.removeOwnedWorktree(path, branch, inspected.gitCommonDir);

This lifecycle handling prevents filesystem pollution and ensures that sensitive code artifacts or temporary build outputs do not persist beyond their intended execution scope, maintaining a clean environment for subsequent graph executions.

Complete Implementation Workflow

The following pattern demonstrates the complete workflow for provisioning and managing isolated worktrees in a Maka Graph context:

// 1. Initialize the worktree executor during host startup
const worktreeChildExecutor = createGitWorktreeChildExecutor({
  storageRoot: '/var/maka/storage',
});

// 2. Provision an isolated workspace for a graph sub-agent
const leaseId = `subagent_worktree_${crypto.randomUUID().replace(/-/g, '')}`;
const binding = await worktreeChildExecutor.provision({
  leaseId,
  sourceCwd: '/repo/project',
  sourceSessionId: parentSessionId,
  sourceProjectId: 'project-1',
});

// 3. Execute sub-agent work, then capture changes as a patch
const patch = await worktreeChildExecutor.capturePatch(binding);
// Store `patch` as an artifact or feed it back to the graph

// 4. Clean up the isolated worktree after graph node completion
await worktreeChildExecutor.retire(binding);

Summary

• Dedicated Git worktrees provide filesystem isolation for each sub-agent in Maka's Graph orchestration, preventing workspace conflicts during concurrent execution of graph nodes.
• The GitWorktreeChildExecutor manages deterministic worktree creation under subagent-worktrees/ directories, with paths derived from lease IDs to support recovery and retry scenarios.
• Isolation guarantees are enforced through inspectOwnedWorktree validation, which rejects worktrees that resolve outside their designated host-owned boundaries to prevent filesystem escape.
• Graph coordination relies on patch capture mechanisms to extract committed changes from isolated worktrees safely before retirement, ensuring only intended modifications propagate through the workflow.
• Explicit lifecycle management via removeOwnedWorktree ensures no transient files or Git branches persist after sub-agent completion, maintaining repository hygiene.

Frequently Asked Questions

How does Maka ensure sub-agent worktrees cannot access files outside their designated paths?

The GitWorktreeChildExecutor validates every worktree through the inspectOwnedWorktree method, which normalizes the worktree path and compares it against the expected host-owned location. If the resolved path differs from the validated boundary, the system throws an error immediately, preventing filesystem escape vulnerabilities that could expose sensitive host data to sub-agents.

Can multiple sub-agents share the same Git worktree simultaneously?

No. Each sub-agent receives a unique worktree identified by a deterministic lease ID (subagent_worktree_<hash>). While the executor may reuse worktree directories across sequential sessions for the same lease ID during recovery scenarios, concurrent sub-agents operate in physically separate worktrees with independent Git branches to prevent race conditions and ensure workspace integrity.

What happens to worktrees when a sub-agent crashes or fails?

The executor's deterministic lease-to-path mapping enables robust recovery. When a session resumes, the system can reattach to existing worktrees using the lease ID or clean them up via removeOwnedWorktree if the lease has expired or been revoked. This ensures that crashed sub-agents do not leave orphaned Git branches or locked working directories that would block subsequent graph executions.

How does the Graph coordinator capture changes from isolated worktrees without breaking isolation?

Through the capturePatch method exposed by GitWorktreeChildExecutor, the AgentGraphCoordinator extracts diffs from the worktree only after verifying a quiescent workspace state where all changes are committed. This patch can then be applied to downstream workspaces or stored as execution artifacts, allowing the graph to propagate changes while maintaining strict filesystem isolation between sub-agents.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}