# How the `ai-memory run` Command Manages Workstreams: A Deep Dive into the 11-Phase Lifecycle

> Discover how the ai-memory run command manages workstreams through its 11-phase lifecycle. Learn about repository fingerprinting, transcript import, and harness process orchestration.

- Repository: [Fabio Akita/ai-memory](https://github.com/akitaonrails/ai-memory)
- Tags: deep-dive
- Published: 2026-08-26

---

**The `ai-memory run` command orchestrates an 11-phase managed workstream lifecycle that ties native harness processes to server-side records, handling everything from repository fingerprinting to transcript import.**

The `ai-memory run` command in the [akitaonrails/ai-memory](https://github.com/akitaonrails/ai-memory) repository implements a sophisticated **workstream management** system that bridges local AI agent processes with persistent server-side state. This managed approach ensures that every native session is tracked, linked, and synchronized with the cloud workstream, enabling features like automatic transcript import and heartbeat monitoring.

## Phase 1: Repository Context and Harness Selection

### Repository Inspection and Fingerprinting

The lifecycle begins with repository discovery. In [`crates/ai-memory-cli/src/commands/run.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/commands/run.rs), the `inspect_repository` function (line 87) determines the checkout path and calculates a repository fingerprint. Simultaneously, `native_home` (lines 30-31) locates where native harness sessions are stored locally. These values establish the foundation for linking local activity to the correct workstream context.

### Automatic Harness Detection

When users omit the `--harness` flag, the CLI performs automatic discovery. The `list_auto_sessions` function (lines 24-53) scans for checkout-local sessions across all supported harnesses defined in `AUTO_HARNESSES`. It then filters these through `filter_usable_auto_sessions` (lines 82-97) to exclude any harnesses whose executables are not present on the system `PATH`.

## Phase 2: Server Preparation and Session Adoption

### Preparing the Managed Run

With harness selection complete, the CLI initiates server-side workstream creation. The `prepare_managed_run` function (lines 64-66) constructs a `PrepareManagedRunRequest` containing the workspace fingerprint, repository details, selected agent, and available agents for auto-selection. This request hits the `/workstream/runs` endpoint. The implementation includes retry logic via `prepare_managed_run_with_retry` (lines 77-99) to handle transient network failures. The server responds with a `PrepareManagedRunResponse` containing the critical `run_id`, `workstream_id`, and optionally a pre-linked native session ID.

### Native Session Adoption

If the workstream lacks a linked session and the harness supports adoption, the CLI attempts to reuse existing local sessions. The `auto_candidates` logic (lines 101-118) identifies potential sessions, while `choose_native_session_interactive` (lines 38-71) provides an interactive picker when multiple candidates exist. This prevents unnecessary session creation when valid local contexts are already available.

## Phase 3: Launch Plan Construction and Process Spawning

### Building the Launch Plan

Before execution, the CLI constructs a `LaunchPlan` that determines execution mode. The `build_preflighted_launch_plan` function (lines 78-89) in [`run.rs`](https://github.com/akitaonrails/ai-memory/blob/main/run.rs) delegates to `build_launch_plan` (located in [`crates/ai-memory-workstream/src/lib.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-workstream/src/lib.rs)) to resolve **Session** versus **Passthrough** mode, handle special flags like `--yolo` and `--fresh`, and determine the executable path and arguments.

### Linking and Spawning

For session-mode runs, the CLI notifies the server of the native session association via `post_json_no_content` (lines 46-60) sending a `LinkManagedRunRequest`. The process spawns with three critical environment variables injected:
- `AI_MEMORY_RUN_ID`
- `AI_MEMORY_WORKSTREAM_ID`
- `AI_MEMORY_HOOK_URL`

These variables enable the harness to send hook events back to the server. The spawn logic resides in the command construction block (lines 97-108).

## Phase 4: Runtime Monitoring

### Heartbeat Maintenance

While the native process executes, a background task maintains the workstream lease. The `send_managed_heartbeat` and `send_managed_heartbeat_with_timeout` functions (lines 53-88) periodically post to `/heartbeat`. The system tolerates server unreachable conditions, entering a quiet retry mode after configurable consecutive failures to prevent log spam while ensuring eventual consistency.

## Phase 5: Termination and Transcript Import

### Process Completion Handling

When the child process exits, the CLI resolves the final state. The `resolve_native_session_after_run` function (lines 105-121) collects the exit code, fetches pending server status, and discovers any newly created native session IDs that weren't known at launch.

### Transcript Import and Finalization

The final phase exports and uploads the execution transcript. The `import_batches` function (lines 93-122) exports the native transcript via `export_transcript`, splits events into size-bounded chunks, and posts them to `/finish`. If the harness provides a context packet (such as Grok or Crush), it is delivered before the first batch via `finish_with_retry` (lines 146-161). Finally, the heartbeat task aborts and the CLI returns the native process exit code (lines 144-145).

## Key Source Files and Architecture

The **workstream management** logic spans four primary crates:

- **[`crates/ai-memory-cli/src/commands/run.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/commands/run.rs)**: Contains the main `run` function (line 78) and `run_from` helper orchestrating the entire lifecycle.
- **[`crates/ai-memory-workstream/src/lib.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-workstream/src/lib.rs)**: Defines `LaunchPlan`, `ManagedHarness`, and helper functions like `build_launch_plan` and `discover_native_session`.
- **[`crates/ai-memory-cli/src/cli.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/cli.rs)**: Defines `RunArgs` and `RunHarnessChoice` structures that parse command-line inputs.
- **[`crates/ai-memory-core/src/lib.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-core/src/lib.rs)**: Houses the protocol definitions including `PrepareManagedRunRequest`, `FinishManagedRunRequest`, and related response structs.

## Practical Usage Examples

```bash

# Run a Codex session, creating a new workstream called "experiment"

ai-memory run codex --workstream experiment --fresh

# Run a Kiro CLI session, automatically selecting the newest checkout-local session

ai-memory run kiro

# Run a native executable not on PATH with explicit harness specification

ai-memory run --executable /usr/local/bin/custom-agent claude --fresh

```

## Summary

- The `ai-memory run` command implements an 11-phase **workstream management** lifecycle that ensures server-side consistency with local execution.
- Repository fingerprinting via `inspect_repository` and automatic harness selection via `list_auto_sessions` provide zero-configuration operation.
- Server coordination uses `PrepareManagedRunRequest` and `LinkManagedRunRequest` to establish the relationship between native processes and workstream records.
- Runtime reliability is maintained through environment variable injection (`AI_MEMORY_RUN_ID`, `AI_MEMORY_WORKSTREAM_ID`, `AI_MEMORY_HOOK_URL`) and robust heartbeat mechanisms.
- Execution artifacts are captured through `export_transcript` and imported via batched `finish` requests, preserving complete session history.

## Frequently Asked Questions

### How does `ai-memory run` handle network interruptions during execution?

The heartbeat implementation in `send_managed_heartbeat_with_retry` (lines 53-88) tolerates transient failures by entering a quiet retry mode after a configurable number of consecutive misses. The native process continues running independently, and the CLI attempts to reconcile state once connectivity returns, ensuring **workstream management** remains resilient to network partitions.

### What happens if I don't specify a harness when running the command?

If the `--harness` flag is omitted, the CLI executes automatic discovery via `list_auto_sessions` (lines 24-53) and `filter_usable_auto_sessions` (lines 82-97). It scans for checkout-local sessions of all supported harnesses and filters for executables present on `PATH`. This allows `ai-memory run` to intelligently select the appropriate agent without explicit configuration.

### Can I reuse an existing local session instead of creating a new one?

Yes. If the workstream has no linked session and the harness supports adoption, the CLI evaluates `auto_candidates` (lines 101-118) to identify reusable sessions. When multiple candidates exist, `choose_native_session_interactive` (lines 38-71) prompts for selection. This adoption logic prevents unnecessary session proliferation while maintaining accurate workstream tracking.

### Where is the server communication logic defined?

The request/response structures used for server communication—such as `PrepareManagedRunRequest`, `LinkManagedRunRequest`, and `FinishManagedRunRequest`—are defined in [`crates/ai-memory-core/src/lib.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-core/src/lib.rs). The CLI uses these structs to communicate with endpoints like `/workstream/runs`, `/heartbeat`, and `/finish` throughout the managed run lifecycle.