launchpad-run

name

launchpad-run

description

Multi-session autonomous agent runner with progress checkpointing, failure recovery, and task dependency management. Uses a controller + sub-agent architecture: the main agent orchestrates state while sub-agents execute tasks in parallel via worktrees. Triggers on '/lp:run' command, or when a task involves many subtasks needing progress persistence, sleep/resume cycles across context windows, recovery from mid-task failures with partial state, or distributed work across multiple agent sessions.

Executable protocol enabling any agent task to run continuously across multiple sessions with automatic progress recovery, task dependency resolution, failure rollback, and standardized error handling. The controller agent orchestrates state and dispatches sub-agents for parallel task execution via git worktrees.

Architecture

[User] → /lp:run
          ↓
[Controller Agent] (this agent — holds lock, manages state)
  ├─ Reads harness-tasks.json + harness-progress.txt
  ├─ Selects batch of independent tasks
  ├─ Dispatches sub-agents in parallel (Task tool, isolation: "worktree")
  ├─ Waits for results
  ├─ Validates each result (runs validation command)
  ├─ Merges successful worktree branches → main branch
  ├─ Updates state
  └─ Picks next batch → repeat

Separation of concerns:

• Controller: state management, task selection, validation, merge, error handling
• Sub-agents: code implementation only (no state access)

Design Principles

1. Controller owns all state — Only the controller reads/writes state files. Sub-agents never touch harness-tasks.json or harness-progress.txt
2. Delegate execution, keep orchestration — Sub-agents implement; the controller validates, merges, and decides
3. Progress files ARE the context — When context window resets, progress files + git history = full recovery
4. Premature completion is the #1 failure mode — Structured task lists with explicit completion criteria prevent declaring victory early
5. Parallelize independent work — Tasks with no mutual dependencies run simultaneously in isolated worktrees
6. Standardize everything grep-able — ERROR on same line, structured timestamps, consistent prefixes
7. Idempotent everything — Init scripts, task execution, environment setup must all be safe to re-run
8. Fail safe, not fail silent — Every failure must have an explicit recovery strategy

Commands

/lp:run                     # Start/resume the controller loop (auto-inits if first run)
/lp:run status              # Show current progress and stats
/lp:run add "task desc"     # Add a task to the list

Progress Persistence (Dual-File System)

Maintain two files in the project working directory:

harness-progress.txt (Append-Only Log)

Free-text log of all controller actions across sessions. Never truncate.

[2025-07-01T10:00:00Z] [SESSION-1] INIT Launchpad runner initialized for project /path/to/project
[2025-07-01T10:00:05Z] [SESSION-1] INIT Environment health check: PASS
[2025-07-01T10:00:10Z] [SESSION-1] LOCK acquired (pid=12345)
[2025-07-01T10:00:11Z] [SESSION-1] BATCH dispatching 3 tasks: [task-001, task-002, task-004]
[2025-07-01T10:00:12Z] [SESSION-1] DISPATCH [task-001] agent=agent_abc123 worktree=harness-task-001
[2025-07-01T10:00:12Z] [SESSION-1] DISPATCH [task-002] agent=agent_def456 worktree=harness-task-002
[2025-07-01T10:00:12Z] [SESSION-1] DISPATCH [task-004] agent=agent_ghi789 worktree=harness-task-004
[2025-07-01T10:08:00Z] [SESSION-1] AGENT_DONE [task-001] agent=agent_abc123 result=success
[2025-07-01T10:08:01Z] [SESSION-1] VALIDATE [task-001] command="npm test -- --testPathPattern=auth" result=PASS
[2025-07-01T10:08:05Z] [SESSION-1] MERGE [task-001] branch=harness-task-001 into=develop (commit abc1234)
[2025-07-01T10:08:06Z] [SESSION-1] Completed [task-001]
[2025-07-01T10:10:00Z] [SESSION-1] AGENT_DONE [task-002] agent=agent_def456 result=success
[2025-07-01T10:10:01Z] [SESSION-1] VALIDATE [task-002] command="npm test -- --testPathPattern=rate-limit" result=FAIL
[2025-07-01T10:10:02Z] [SESSION-1] DISCARD [task-002] worktree=harness-task-002 reason="validation failed"
[2025-07-01T10:10:03Z] [SESSION-1] ERROR [task-002] [TEST_FAIL] Rate limit middleware test: expected 429 got 200
[2025-07-01T10:12:00Z] [SESSION-1] AGENT_DONE [task-004] agent=agent_ghi789 result=error
[2025-07-01T10:12:01Z] [SESSION-1] DISCARD [task-004] worktree=harness-task-004 reason="agent reported failure"
[2025-07-01T10:12:02Z] [SESSION-1] ERROR [task-004] [AGENT_FAIL] Sub-agent could not resolve import errors
[2025-07-01T10:12:03Z] [SESSION-1] STATS tasks_total=8 completed=1 failed=2 in_batch=0 pending=4 blocked=1 attempts_total=5

harness-tasks.json (Structured State)

{
  "version": 3,
  "created": "2025-07-01T10:00:00Z",
  "session_config": {
    "max_tasks_per_session": 20,
    "max_sessions": 50,
    "max_parallel_agents": 3
  },
  "tasks": [
    {
      "id": "task-001",
      "title": "Implement user authentication",
      "status": "completed",
      "priority": "P0",
      "depends_on": [],
      "attempts": 1,
      "max_attempts": 3,
      "context": "Create JWT-based auth with login/register endpoints in src/auth/",
      "files_hint": ["src/auth/", "src/middleware/auth.ts"],
      "validation": {
        "command": "npm test -- --testPathPattern=auth",
        "timeout_seconds": 300
      },
      "on_failure": {
        "cleanup": null
      },
      "error_log": [],
      "agent_id": null,
      "worktree_branch": null,
      "completed_at": "2025-07-01T10:08:06Z"
    },
    {
      "id": "task-002",
      "title": "Add rate limiting",
      "status": "failed",
      "priority": "P1",
      "depends_on": [],
      "attempts": 1,
      "max_attempts": 3,
      "context": "Add Redis-backed rate limiting middleware, 100 req/min per IP",
      "files_hint": ["src/middleware/rate-limit.ts"],
      "validation": {
        "command": "npm test -- --testPathPattern=rate-limit",
        "timeout_seconds": 120
      },
      "on_failure": {
        "cleanup": "docker compose down redis"
      },
      "error_log": ["[TEST_FAIL] Rate limit middleware test: expected 429 got 200"],
      "agent_id": null,
      "worktree_branch": null,
      "completed_at": null
    },
    {
      "id": "task-003",
      "title": "Add OAuth providers",
      "status": "pending",
      "priority": "P1",
      "depends_on": ["task-001"],
      "attempts": 0,
      "max_attempts": 3,
      "context": "Add Google and GitHub OAuth using passport.js, integrate with existing auth from task-001",
      "files_hint": ["src/auth/oauth/"],
      "validation": {
        "command": "npm test -- --testPathPattern=oauth",
        "timeout_seconds": 180
      },
      "on_failure": {
        "cleanup": null
      },
      "error_log": [],
      "agent_id": null,
      "worktree_branch": null,
      "completed_at": null
    }
  ],
  "session_count": 1,
  "last_session": "2025-07-01T10:12:03Z"
}

Key fields:

• context: Detailed description for sub-agent prompt (what to implement, constraints, approach)
• files_hint: Suggested files/directories the sub-agent should focus on
• agent_id: ID of the dispatched sub-agent (set during in_progress, cleared after)
• worktree_branch: Name of the worktree branch (set during in_progress, cleared after)
• session_config.max_parallel_agents: Maximum concurrent sub-agents per batch (default: 3)

Task statuses: pending → in_progress (while sub-agent is running) → completed or failed.

Session boundary: A session starts when the controller begins executing the Session Start protocol and ends when a Stopping Condition is met or the context window resets. Each session gets a unique SESSION-N identifier (N = session_count after increment).

Concurrency Control

Before modifying harness-tasks.json, acquire an exclusive lock using portable mkdir (atomic on all POSIX systems, works on both macOS and Linux):

# Acquire lock (fail fast if another controller is running)
LOCKDIR="/tmp/harness-$(printf '%s' "$(pwd)" | shasum -a 256 2>/dev/null || sha256sum | cut -c1-8).lock"
if ! mkdir "$LOCKDIR" 2>/dev/null; then
  # Check if lock holder is still alive
  LOCK_PID=$(cat "$LOCKDIR/pid" 2>/dev/null)
  if [ -n "$LOCK_PID" ] && kill -0 "$LOCK_PID" 2>/dev/null; then
    echo "ERROR: Another session is active (pid=$LOCK_PID)"; exit 1
  fi
  # Stale lock — atomically reclaim via mv to avoid TOCTOU race
  STALE="$LOCKDIR.stale.$$"
  if mv "$LOCKDIR" "$STALE" 2>/dev/null; then
    rm -rf "$STALE"
    mkdir "$LOCKDIR" || { echo "ERROR: Lock contention"; exit 1; }
    echo "WARN: Removed stale lock${LOCK_PID:+ from pid=$LOCK_PID}"
  else
    echo "ERROR: Another agent reclaimed the lock"; exit 1
  fi
fi
echo "$$" > "$LOCKDIR/pid"
trap 'rm -rf "$LOCKDIR"' EXIT

Log lock acquisition: [timestamp] [SESSION-N] LOCK acquired (pid=<PID>) Log lock release: [timestamp] [SESSION-N] LOCK released

The lock is held for the entire session by the controller. Sub-agents do NOT acquire or need the lock — they work in isolated worktrees and never touch state files.

Controller Loop Protocol

Session Start (Execute Every Time)

1. Auto-init if first run: If harness-tasks.json does not exist:
   • Create harness-progress.txt with INIT Launchpad runner initialized for project <cwd>
   • Create harness-tasks.json with empty task list and default session_config (including max_parallel_agents: 3)
   • Optionally create harness-init.sh template (chmod +x)
   • Ask user: add state files to .gitignore?
   • Prompt user to add tasks (via interactive input or /lp:run add), then continue
2. Read state: Read last 200 lines of harness-progress.txt + full harness-tasks.json. If JSON is unparseable, see JSON corruption recovery in Error Handling.
3. Read git: Run git log --oneline -20 and git diff --stat to detect uncommitted work
4. Acquire lock: Fail if another session is active
5. Recover interrupted tasks (see Context Window Recovery below)
6. Health check: Run harness-init.sh if it exists
7. Track session: Increment session_count in JSON. Check session_count against max_sessions — if reached, log STATS and STOP. Initialize per-session task counter to 0.
8. Select and dispatch batch using Batch Selection Algorithm below

Batch Selection Algorithm

Before selecting, run dependency validation:

1. Cycle detection: For each non-completed task, walk depends_on transitively. If any task appears in its own chain, mark it failed with [DEPENDENCY] Circular dependency detected: task-A -> task-B -> task-A. Self-references (depends_on includes own id) are also cycles.
2. Blocked propagation: If a task's depends_on includes a task that is failed and will never be retried (either attempts >= max_attempts OR its error_log contains a [DEPENDENCY] entry), mark the blocked task as failed with [DEPENDENCY] Blocked by failed task-XXX. Repeat until no more tasks can be propagated.

Then build the eligible task pool:

1. Tasks with status: "pending" where ALL depends_on tasks are completed — sorted by priority (P0 > P1 > P2), then by id (lowest first)
2. Tasks with status: "failed" where attempts < max_attempts and ALL depends_on are completed — sorted by priority, then oldest failure first
3. If no eligible tasks remain → log final STATS → STOP

Batch construction — from the eligible pool, select up to max_parallel_agents tasks that can safely run in parallel:

1. Start with the highest-priority eligible task. Add it to the batch.
2. For each remaining eligible task (in priority order), add it to the batch ONLY IF:
   • It does NOT depend on any task already in the batch
   • No task in the batch depends on it
   • Its files_hint does NOT overlap with any batch task's files_hint (directory-level comparison: src/auth/ overlaps with src/auth/oauth/)
   • Batch size < max_parallel_agents
3. If files_hint is empty for a task, treat it as potentially conflicting — do NOT batch it with other tasks (run solo).

Log: [timestamp] [SESSION-N] BATCH dispatching N tasks: [task-001, task-002, ...]

Sub-agent Dispatch Protocol

For each task in the batch, dispatch a sub-agent using the Task tool with these parameters:

Task tool call:
  subagent_type: "general-purpose"
  isolation: "worktree"
  description: "<task-id>: <short title>"
  prompt: <see Sub-agent Prompt Template below>
  run_in_background: true

All sub-agents in a batch MUST be dispatched in a single message (parallel Task tool calls) so they run concurrently.

After dispatching, record for each task:

• Set status: "in_progress"
• Set agent_id to the returned agent ID
• Set worktree_branch to "harness-<task-id>"
• Log: DISPATCH [task-id] agent=<agent_id> worktree=harness-<task-id>

Sub-agent Prompt Template

You are a worker agent executing a single task for a Launchpad-managed project.

## Task
- ID: {task.id}
- Title: {task.title}
- Description: {task.context}

## Scope
- Focus on these files/directories: {task.files_hint}
- Make the MINIMUM changes needed to complete this task
- Do NOT modify files outside your scope unless absolutely necessary
- Do NOT read or modify: harness-progress.txt, harness-tasks.json

## Validation
When done, run this command to verify your work:
{task.validation.command}

If validation fails, fix the issues and re-run until it passes or you've exhausted your attempts.

## Completion
- Commit all changes with message: "[{task.id}] {task.title}"
- Your last message must clearly state either:
  - "RESULT:SUCCESS" if validation passed
  - "RESULT:FAIL <reason>" if you could not complete the task

## Context
- Project root: {project_path}
- Current branch: {current_branch}
- You are working in an isolated git worktree — your changes will be merged by the controller.
{additional_context_from_previous_attempts_if_retry}

If this is a retry (attempts > 0), append to the prompt:

## Previous Attempt(s)
This task has been attempted {attempts} time(s) before and failed.
Error log from previous attempts:
{task.error_log joined by newline}

Avoid repeating the same mistakes. Consider a different approach.

Collecting Sub-agent Results

After dispatching, the controller waits for sub-agent completion notifications. For each completed sub-agent:

1. Read result: Check the sub-agent's final message for RESULT:SUCCESS or RESULT:FAIL <reason>
2. Log: AGENT_DONE [task-id] agent=<agent_id> result=<success|error>

Process completed sub-agents as they finish (do not wait for the entire batch). For each:

On sub-agent SUCCESS:

1. Validate in worktree: Run validation.command in the worktree directory (if the sub-agent already validated, re-validate from controller to confirm)

   cd <worktree_path> && timeout <timeout_seconds> <validation_command>
   

2. If validation PASS:
   • Log: VALIDATE [task-id] command="<cmd>" result=PASS
   • Merge worktree branch into main working branch (see Merge Protocol below)
   • Set status: "completed", completed_at: <now>, clear agent_id and worktree_branch
   • Log: Completed [task-id]
3. If validation FAIL:
   • Log: VALIDATE [task-id] command="<cmd>" result=FAIL
   • Discard worktree (automatic cleanup or git worktree remove)
   • Increment attempts, append error to error_log
   • Set status: "failed", clear agent_id and worktree_branch
   • Log: DISCARD [task-id] worktree=<branch> reason="validation failed"
   • Log: ERROR [task-id] [TEST_FAIL] <failure details>

On sub-agent FAIL:

1. Discard worktree
2. Increment attempts, append agent's failure reason to error_log
3. Set status: "failed", clear agent_id and worktree_branch
4. Log: DISCARD [task-id] worktree=<branch> reason="agent reported failure"
5. Log: ERROR [task-id] [AGENT_FAIL] <reason from agent>

Merge Protocol

When merging a successful worktree branch into the main working branch:

# From the main working directory (NOT the worktree)
git merge --no-ff "harness-<task-id>" -m "Merge [<task-id>] <task title>"

Merge conflict handling:

• If merge conflicts occur, the controller attempts auto-resolution:
  1. Check if conflicts are in files outside the task's files_hint — if so, the task touched out-of-scope files. Log ERROR [task-id] [MERGE_CONFLICT] Out-of-scope file conflict and discard.
  2. If conflicts are within scope, attempt git merge --abort, then try rebasing the worktree branch:

     git merge --abort
     cd <worktree_path> && git rebase <main_branch>
     

     If rebase succeeds, re-validate and retry merge.
  3. If still conflicting, discard the worktree and mark task as failed with [MERGE_CONFLICT].

Merge ordering: When multiple sub-agents in the same batch succeed, merge them one at a time in task-id order. After each merge, subsequent merges may conflict — handle per above.

After all sub-agents in the batch are processed, increment per-session task counter by batch size. Check stopping conditions, then pick next batch.

Stopping Conditions

• All tasks completed
• All remaining tasks failed at max_attempts or blocked by failed dependencies
• session_config.max_tasks_per_session reached for this session
• session_config.max_sessions reached across all sessions
• User interrupts

Context Window Recovery Protocol

When a new session starts and finds tasks with status: "in_progress":

These are tasks whose sub-agents were dispatched but the controller's context window reset before results were collected.

For each in_progress task:

1. Check if worktree exists:

   git worktree list | grep "harness-<task-id>"
   

2. If worktree exists with commits:

   • The sub-agent likely completed work but the controller didn't collect it
   • Run validation.command in the worktree directory
   • If PASS → merge, mark completed
   • If FAIL → discard worktree, mark failed
   • Log: RECOVERY [task-id] action="validated orphaned worktree" reason="controller session timeout"

3. If worktree exists but empty (no commits beyond branch point):

   • Sub-agent was interrupted or failed silently
   • Remove worktree: git worktree remove <path> --force
   • Mark failed with [SESSION_TIMEOUT] Sub-agent work incomplete
   • Log: RECOVERY [task-id] action="removed empty worktree" reason="no sub-agent progress"

4. If no worktree found:

   • Worktree was already cleaned up (sub-agent finished, Task tool cleaned up)
   • Check if worktree_branch exists as a git branch: git branch --list "harness-<task-id>"
   • If branch exists with commits → validate and merge/discard as above
   • If no branch → mark failed with [SESSION_TIMEOUT] No worktree or branch found

5. Clear transient fields: Set agent_id: null, worktree_branch: null after recovery

Error Handling & Recovery Strategies

Each error category has a default recovery strategy:

Category	Default Recovery	Controller Action
ENV_SETUP	Re-run init, then STOP if still failing	Run harness-init.sh again immediately. If fails twice, log and stop — environment is broken
TASK_EXEC	Discard worktree, retry with new sub-agent	Discard worktree, increment attempts, re-dispatch in next batch if attempts < max_attempts
TEST_FAIL	Discard worktree, retry with error context	Discard worktree, append test output to error_log, retry — sub-agent gets previous error in prompt
AGENT_FAIL	Discard worktree, retry	Sub-agent reported inability to complete. Discard worktree, retry with error context in prompt
MERGE_CONFLICT	Discard worktree, retry solo	Merge failed. Discard worktree, retry — next attempt runs solo (not batched) to avoid conflicts
TIMEOUT	Kill validation, discard, retry	Validation timed out. Discard worktree, retry (consider increasing timeout or splitting task)
DEPENDENCY	Skip task, mark blocked	Log which dependency failed, mark task as failed with dependency reason
SESSION_TIMEOUT	Use Context Window Recovery Protocol	New session assesses orphaned worktrees via Recovery Protocol

Retry isolation: When a task fails with MERGE_CONFLICT, set an internal flag so it runs solo (batch size 1) on the next attempt, avoiding parallel merge issues.

JSON corruption: If harness-tasks.json cannot be parsed, check for harness-tasks.json.bak (written before each modification). If backup exists and is valid, restore from it. If no valid backup, log ERROR [ENV_SETUP] harness-tasks.json corrupted and unrecoverable and STOP.

Backup protocol: Before every write to harness-tasks.json, copy the current file to harness-tasks.json.bak.

Orphaned worktree cleanup: At session start, after recovery, list all worktrees matching harness-task-* pattern. Remove any that don't correspond to an in_progress task:

git worktree list --porcelain | grep "harness-task-"

Environment Initialization

If harness-init.sh exists in the project root, run it at every session start. The script must be idempotent.

Example harness-init.sh:

#!/bin/bash
set -e
npm install 2>/dev/null || pip install -r requirements.txt 2>/dev/null || true
curl -sf http://localhost:5432 >/dev/null 2>&1 || echo "WARN: DB not reachable"
npm test -- --bail --silent 2>/dev/null || echo "WARN: Smoke test failed"
echo "Environment health check complete"

Standardized Log Format

All log entries use grep-friendly format on a single line:

[ISO-timestamp] [SESSION-N] <TYPE> [task-id]? [category]? message

[task-id] and [category] are included when applicable (task-scoped entries). Session-level entries (INIT, LOCK, STATS, BATCH) omit task-id.

Types: INIT, BATCH, DISPATCH, AGENT_DONE, VALIDATE, MERGE, DISCARD, Completed, ERROR, ROLLBACK, RECOVERY, STATS, LOCK, WARN

Error categories: ENV_SETUP, TASK_EXEC, TEST_FAIL, AGENT_FAIL, MERGE_CONFLICT, TIMEOUT, DEPENDENCY, SESSION_TIMEOUT

Filtering:

grep "ERROR" harness-progress.txt                        # All errors
grep "AGENT_FAIL" harness-progress.txt                   # Sub-agent failures
grep "MERGE_CONFLICT" harness-progress.txt               # Merge issues
grep "DISPATCH" harness-progress.txt                     # All dispatches
grep "BATCH" harness-progress.txt                        # All batch starts
grep "SESSION-3" harness-progress.txt                    # All session 3 activity
grep "STATS" harness-progress.txt                        # All session summaries
grep "RECOVERY" harness-progress.txt                     # All recovery actions

Session Statistics

At session end, update harness-tasks.json: increment session_count, set last_session to current timestamp. Then append:

[timestamp] [SESSION-N] STATS tasks_total=10 completed=7 failed=1 in_batch=0 pending=1 blocked=1 attempts_total=12 batches_dispatched=4

blocked is computed at stats time: count of pending tasks whose depends_on includes a permanently failed task. It is not a stored status value. in_batch should be 0 at session end (all sub-agents collected). Non-zero indicates abnormal termination.

Status Command (/lp:run status)

Read harness-tasks.json and harness-progress.txt, then display:

1. Task summary: count by status (completed, failed, in_progress, pending, blocked). blocked = pending tasks whose depends_on includes a permanently failed task (computed, not a stored status).
2. Per-task one-liner: [status] task-id: title (attempts/max_attempts) [agent=X if in_progress]
3. Active worktrees: git worktree list | grep harness-task
4. Last 5 lines from harness-progress.txt
5. Session count and last session timestamp

Does NOT acquire the lock (read-only operation).

Add Command (/lp:run add)

Append a new task to harness-tasks.json with auto-incremented id (task-NNN), status pending, default max_attempts: 3, empty depends_on, and no validation command. Prompt user for fields: priority, depends_on, context (required — sub-agent needs this), files_hint, validation.command, timeout_seconds. Requires lock acquisition (modifies JSON).

Tool Dependencies

Requires: Bash, file read/write, git, Task tool (for sub-agent dispatch with isolation: "worktree"). All operations must be executed from the project root directory. Does NOT require: specific MCP servers, programming languages, or test frameworks.