all-hands-cli 0.1.0

package/docs/harness/cli/schema-and-validation-commands.md

@@ -0,0 +1,154 @@
+---
+description: "Schema definitions and validation pipeline: how YAML schemas enforce file structure for prompts, specs, alignments, validation suites (with tools field and body sections), and agent profiles, with runtime Zod validation for template variables. Includes array item-type enforcement and the SPEC_TYPE template variable registry."
+---
+
+# Schema and Validation Commands
+
+## Intent
+
+The harness manages many structured file types (prompts, specs, alignment docs, agent profiles, validation suites). Each has a required frontmatter shape and sometimes body structure. The schema system is the single source of truth for these requirements, serving two audiences:
+
+1. **Agents** query schemas to understand how to write valid files (`ah schema <type>`)
+2. **Validation** checks files against schemas before they enter the pipeline (`ah validate <file>`)
+
+## Two Validation Approaches
+
+The codebase uses two complementary validation strategies depending on the file type:
+
+```mermaid
+flowchart TD
+    File["Input File"] --> Detect{"Detect schema type"}
+    Detect -->|YAML schema exists| Static["Static YAML Schema<br/>prompt, spec, alignment,<br/>documentation, validation-suite"]
+    Detect -->|Zod schema| Runtime["Runtime Zod Schema<br/>agent-profile, template-vars"]
+    Static --> FrontmatterParse["Extract frontmatter"]
+    FrontmatterParse --> FieldValidation["Validate each field<br/>against SchemaField rules"]
+    Runtime --> ZodParse["Zod safeParse"]
+    ZodParse --> Semantic["Semantic validation<br/>(cross-field checks)"]
+```
+
+### Static YAML Schemas
+
+YAML schema files in `.allhands/schemas/` define frontmatter field requirements. [ref:.allhands/harness/src/lib/schema.ts:loadSchema:c65e65d] reads and caches these definitions. [ref:.allhands/harness/src/lib/schema.ts:listSchemas:c65e65d] discovers available types by scanning the schema directory.
+
+[ref:.allhands/harness/src/lib/schema.ts:validateField:c65e65d] checks individual values against their field definition, supporting these types:
+
+| Type | Validation Rule |
+|------|----------------|
+| `string` | `typeof === 'string'` |
+| `integer` | `typeof === 'number'` and `Number.isInteger()` |
+| `boolean` | `typeof === 'boolean'` |
+| `date` | String parseable as ISO 8601 |
+| `enum` | Value in allowed `values` list |
+| `array` | `Array.isArray()`, plus item-type enforcement when schema specifies `items` |
+| `object` | Recursive property validation via nested `properties` |
+
+When a schema field declares `items` (e.g., `items: string`), [ref:.allhands/harness/src/lib/schema.ts:validateField:c65e65d] enforces that every element matches the declared type. For example, `tools: [123]` is rejected when the schema specifies `items: string`. Integer item validation also catches floats -- `[1, 2.5]` fails against `items: integer`. Arrays without an `items` constraint accept mixed types.
+
+### Runtime Zod Schemas
+
+For types requiring cross-field validation or normalization from YAML snake_case to TypeScript camelCase:
+
+**Agent profiles**: [ref:.allhands/harness/src/lib/schemas/agent-profile.ts:validateProfileSemantics:fb892e5] performs semantic validation beyond schema checks -- verifying that template variables referenced in `message_template` match the declared `template_vars` list, and that no unknown variables are used.
+
+**Template variables**: [ref:.allhands/harness/src/lib/schemas/template-vars.ts:validateTemplateString:730f114] extracts `${VAR_NAME}` references from templates and validates each against the registry of known variables. [ref:.allhands/harness/src/lib/schemas/template-vars.ts:validateContext:730f114] checks that all required variables have valid values at resolution time.
+
+The template variable registry [ref:.allhands/harness/src/lib/schemas/template-vars.ts:TemplateVars:730f114] defines all valid variables with individual Zod schemas:
+
+| Variable | Type | Description |
+|----------|------|-------------|
+| `SPEC_PATH` | `string` | Path to spec file |
+| `ALIGNMENT_PATH` | `string` | Path to alignment doc |
+| `PROMPTS_FOLDER` | `string` | Path to prompts directory |
+| `PROMPT_PATH` | `string` | Path to specific prompt file |
+| `OUTPUT_PATH` | `string` | Output file path |
+| `PLANNING_FOLDER` | `string` | Path to `.planning/{branch}` directory |
+| `SPEC_NAME` | `string` | Current spec name |
+| `PROMPT_NUMBER` | `string` (regex: `/^\d{2}$/`) | Two-digit prompt number |
+| `BRANCH` | `string` | Current git branch name |
+| `SPEC_TYPE` | `string` | Spec type from frontmatter (milestone, investigation, optimization, refactor, documentation, triage) |
+| `HYPOTHESIS_DOMAINS` | `string` | Comma-separated hypothesis domains from settings.json |
+
+[ref:.allhands/harness/src/lib/schemas/template-vars.ts:TEMPLATE_VAR_NAMES:730f114] exports the full variable name list for runtime validation.
+
+## Schema Type Detection
+
+The system can automatically determine which schema applies to a file:
+
+[ref:.allhands/harness/src/lib/schema.ts:detectSchemaType:c65e65d] uses glob pattern matching against known paths:
+
+| Pattern | Schema Type |
+|---------|-------------|
+| `.planning/**/prompts/*.md` | `prompt` |
+| `.planning/**/alignment.md` | `alignment` |
+| `specs/**/*.spec.md` | `spec` |
+| `docs/**/*.md` | `documentation` |
+| `.allhands/validation/*.md` | `validation-suite` |
+| `.allhands/skills/*/SKILL.md` | `skill` |
+
+[ref:.allhands/harness/src/lib/schema.ts:inferSchemaType:c65e65d] provides a string-matching fallback when glob patterns fail, using path segments and file name patterns.
+
+## CLI Commands
+
+### `ah schema <type> [property]`
+
+[ref:.allhands/harness/src/commands/schema.ts:register:38074a4] exposes schema definitions to agents. Given a type name, it reads the corresponding YAML schema and outputs it. The optional `property` argument extracts a single top-level key, reducing output for agents that only need to understand one aspect of a schema.
+
+[ref:.allhands/harness/src/commands/schema.ts:getAvailableSchemas:38074a4] lists all `.yaml` files in the schemas directory when an unknown type is requested, guiding agents toward valid types.
+
+### `ah validate <file>`
+
+[ref:.allhands/harness/src/commands/validate.ts:register:66f613b] validates a file against its detected or inferred schema. The validation pipeline:
+
+1. Read the file
+2. Detect schema type from path (glob match, then string inference)
+3. Extract frontmatter
+4. Validate against schema fields
+5. Format errors with [ref:.allhands/harness/src/lib/schema.ts:formatErrors:c65e65d]
+
+### `ah validation-tools list`
+
+[ref:.allhands/harness/src/commands/validation-tools.ts:register:d44fa2a] discovers validation suite definitions in `.allhands/validation/`. Each suite is a markdown file with frontmatter declaring:
+
+| Field | Type | Purpose |
+|-------|------|---------|
+| `name` | `string` | Unique suite identifier (matches filename) |
+| `description` | `string` | When/why to use this suite |
+| `globs` | `string[]` | File patterns the suite validates (used for discovery) |
+| `tools` | `string[]` | CLI tools and packages the suite uses (e.g., `agent-browser`, `playwright`) |
+
+The `tools` field enables agent-to-suite mapping -- agents can find which validation suites are relevant based on the tools they have available. [ref:.allhands/harness/src/commands/validation-tools.ts:listValidationSuites:d44fa2a] delegates frontmatter validation to [ref:.allhands/harness/src/lib/schema.ts:validateFrontmatter:c65e65d], ensuring suites with invalid or incomplete frontmatter are silently excluded from the listing rather than causing errors. This delegation keeps schema enforcement centralized in `lib/schema.ts` rather than duplicated in command files.
+
+## Validation Suite Schema
+
+The `validation-suite` schema type ([ref:.allhands/schemas/validation-suite.yaml::d45ebc8]) defines the structure for two-dimensional validation playbooks in `.allhands/validation/`. Per **Agentic Validation Tooling**, every suite has both a stochastic dimension (agent-driven exploratory testing) and a deterministic dimension (CI-gated binary pass/fail).
+
+### Frontmatter Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | `string` | Yes | Unique suite identifier matching filename |
+| `description` | `string` | Yes | Use case description for suite discovery |
+| `globs` | `array` (`items: string`) | Yes | File patterns this suite validates |
+| `tools` | `array` (`items: string`) | Yes | CLI tools and packages used by the suite |
+
+The `tools` and `globs` fields both enforce item-type validation via `items: string` in the schema -- non-string array elements are rejected at validation time.
+
+### Body Sections
+
+The schema defines 5 body sections that structure the validation playbook:
+
+| Section | Required | Content |
+|---------|----------|---------|
+| **Purpose** | Yes | Quality aspects this suite validates (stability, performance, UX, accessibility) |
+| **Tooling** | Yes | Tools used, installation, and configuration |
+| **Stochastic Validation** | Yes | Agent-driven exploratory playbook: patterns, edge case strategies, death spiral escape hatches |
+| **Deterministic Integration** | Yes | CI-gated scripted validation: test scripts, success/failure criteria, artifact capture |
+| **ENV Configuration** | No | Environment variables needed for both dimensions (only when suite requires external configuration) |
+
+This structure reflects the crystallization lifecycle from principles: stochastic exploration discovers patterns, patterns crystallize into deterministic checks, deterministic checks entrench in CI/CD, and stochastic exploration shifts to the frontier.
+
+## Key Design Decisions
+
+- **YAML for static schemas, Zod for runtime**: YAML schemas are agent-readable (via `ah schema`) and work for simple field-level checks. Zod schemas handle normalization and cross-field logic that YAML cannot express.
+- **Schema caching**: [ref:.allhands/harness/src/lib/schema.ts:loadSchema:c65e65d] caches parsed schemas in memory, avoiding repeated filesystem reads during validation of multiple files.
+- **Defaults via schema**: [ref:.allhands/harness/src/lib/schema.ts:applyDefaults:c65e65d] fills missing frontmatter fields from schema defaults, enabling minimal frontmatter in files while maintaining complete data.

package/docs/harness/cli/search-commands.md

@@ -0,0 +1,97 @@
+---
+description: "Knowledge retrieval commands for agents: local solution and memory search via keyword scoring, plus external web research through Perplexity, Tavily, and Context7 integrations."
+---
+
+## Intent
+
+Agents need to retrieve knowledge from two distinct sources: **local project knowledge** (solutions, memories) and **external web knowledge** (documentation, research). The search commands provide a unified CLI surface for both, with consistent JSON output that agents can parse. The local search commands use weighted keyword scoring against structured frontmatter rather than full-text search, trading recall for precision and avoiding embedding infrastructure.
+
+## Local Knowledge Search
+
+### Solutions Search
+
+[ref:.allhands/harness/src/commands/solutions.ts:searchSolutions:19e47dd] searches documented solutions in `docs/solutions/`. Solutions are markdown files with YAML frontmatter containing structured fields (title, tags, component, symptoms, root_cause, severity).
+
+Scoring weights determine field importance:
+
+| Field | Weight | Rationale |
+|-------|--------|-----------|
+| title | 3 | Strongest signal -- direct topic match |
+| tags | 3 | Curated identifiers, high precision |
+| component | 2 | Narrows to subsystem |
+| symptoms | 2 | Matches problem description |
+| problem_type | 1 | Broad categorization |
+| root_cause | 1 | Technical detail |
+
+[ref:.allhands/harness/src/commands/solutions.ts:scoreSolution:19e47dd] computes a cumulative score per keyword across all fields. [ref:.allhands/harness/src/commands/solutions.ts:extractKeywords:19e47dd] handles quoted phrases and whitespace splitting, allowing queries like `"tmux session" timeout`.
+
+### Memories Search
+
+[ref:.allhands/harness/src/commands/memories.ts:searchMemories:49c8ec9] searches project memories stored as markdown tables in `docs/memories.md`. Each table row has Name, Domain, Source, and Description columns grouped under section headers.
+
+[ref:.allhands/harness/src/commands/memories.ts:scoreMemory:49c8ec9] applies similar weighted scoring:
+
+| Field | Weight |
+|-------|--------|
+| name | 3 |
+| description | 2 |
+| domain | 2 |
+| source | 1 |
+
+Memories support additional filtering by `--domain` and `--source` before scoring, enabling queries like `ah memories search "hook" --domain planning`.
+
+### Shared Search Design
+
+Both local search commands share these characteristics:
+- Keyword extraction with quoted phrase support ([ref:.allhands/harness/src/commands/solutions.ts:extractKeywords:19e47dd])
+- Cumulative scoring across multiple fields
+- Results sorted by score descending, truncated to `--limit`
+- JSON output with `matchedFields` array explaining why each result matched
+- Zero external dependencies (pure filesystem reads + YAML parsing)
+
+## External Web Research
+
+### Perplexity
+
+[ref:.allhands/harness/src/commands/perplexity.ts:callPerplexityApi:e041bed] sends queries to Perplexity's `sonar-pro` model, which returns AI-synthesized answers with citation URLs. The distinctive feature is the `--challenge` flag, which sends Perplexity's findings to [ref:.allhands/harness/src/commands/perplexity.ts:callGrokChallengeApi:e041bed] (Grok/X.AI) for adversarial validation. The Grok challenger prompt specifically targets contradicting opinions, newer alternatives, and developer sentiment from X/Twitter posts.
+
+```mermaid
+sequenceDiagram
+    participant Agent
+    participant Perplexity as Perplexity API
+    participant Grok as Grok/X.AI API
+
+    Agent->>Perplexity: research query
+    Perplexity-->>Agent: findings + citations
+
+    opt --challenge flag
+        Agent->>Grok: findings + original query
+        Note right of Grok: Searches X for contradictions,<br/>alternatives, sentiment
+        Grok-->>Agent: challenge analysis + sources
+    end
+```
+
+### Tavily
+
+[ref:.allhands/harness/src/commands/tavily.ts:callTavilyApi:3ab56fe] provides two capabilities:
+
+- **Search** (`ah tavily search`): Web search with optional LLM-generated answer, configurable max results (capped at 20)
+- **Extract** (`ah tavily extract`): Full content extraction from up to 20 URLs, returned as markdown
+
+### Context7
+
+Context7 bridges from library names to documentation context in a two-step flow:
+
+1. `ah context7 search <library>` -- Finds libraries by name, returns IDs with trust scores and snippet counts
+2. `ah context7 context <libraryId> <query>` -- Retrieves documentation context for a known library, supporting both JSON (structured docs) and `--text` (plain text for direct LLM consumption) output modes
+
+## API Key Requirements
+
+| Command | Environment Variable | Required |
+|---------|---------------------|----------|
+| `ah perplexity research` | `PERPLEXITY_API_KEY` | Yes |
+| `ah perplexity research --challenge` | `X_AI_API_KEY` | Additionally required |
+| `ah tavily search` / `extract` | `TAVILY_API_KEY` | Yes |
+| `ah context7 search` / `context` | `CONTEXT7_API_KEY` | Yes |
+
+All external commands use abort controllers with configurable timeouts (default 60s for Perplexity, 120s for Grok/Tavily/Context7) and surface errors as structured JSON when `--json` is passed.

package/docs/harness/cli/spawn-command.md

@@ -0,0 +1,136 @@
+---
+description: "Agent spawning system that uses tmux sessions and windows to run isolated Claude Code agents, with profile-based configuration, flowOverride for type-routed spawning, template context resolution (including SPEC_TYPE and HYPOTHESIS_DOMAINS), and persistent session state tracking."
+---
+
+## Intent
+
+The spawn system solves the problem of running multiple concurrent Claude Code agents in isolated environments while maintaining a coherent session model. Each agent runs in its own tmux window with dedicated environment variables, ensuring MCP daemon isolation via AGENT_ID and preventing resource conflicts between agents.
+
+The key design decision is that **tmux windows are the unit of agent isolation**. The window name becomes the AGENT_ID, which cascades into MCP daemon socket paths, trace event attribution, and session state tracking.
+
+## Agent Lifecycle
+
+```mermaid
+stateDiagram-v2
+    [*] --> ProfileLoaded: spawnAgentFromProfile
+    [*] --> ConfigBuilt: spawnAgent (direct)
+    ProfileLoaded --> Validated: buildAgentInvocation
+    Validated --> ConfigBuilt: Convert to SpawnConfig
+    ConfigBuilt --> WindowCreated: createWindow (detached)
+    WindowCreated --> Registered: registerSpawnedAgent
+    Registered --> EnvSet: buildAgentEnv
+    EnvSet --> LauncherWritten: Write launcher script
+    LauncherWritten --> Running: sendKeys (exec bash launcher)
+    Running --> Focused: focusWindow=true
+    Running --> Background: focusWindow=false
+    Running --> [*]: Agent exits, window closes
+```
+
+## Three Spawning Paths
+
+| Path | Entry Point | Use Case |
+|------|-------------|----------|
+| Profile-based | [ref:.allhands/harness/src/lib/tmux.ts:spawnAgentFromProfile:553666b] | Preferred path. Loads YAML profile from `.allhands/agents/`, validates template variables, resolves message template. Supports `flowOverride` for type-routed spawning. |
+| Direct spawn | [ref:.allhands/harness/src/lib/tmux.ts:spawnAgent:553666b] | Lower-level. Takes a complete SpawnConfig with explicit flow path and preamble |
+| Custom flow | [ref:.allhands/harness/src/lib/tmux.ts:spawnCustomFlow:553666b] | Ad-hoc flows. Takes an absolute flow path and custom message, uses a generated window name |
+
+The `ah spawn codesearch` CLI command ([ref:.allhands/harness/src/commands/spawn.ts:CodesearchCommand:71f3aed]) takes a separate approach entirely -- it uses the OpenCode SDK's AgentRunner rather than tmux, running an AI agent with ast-grep, ripgrep, and LSP tools within a single process with a tool budget and step limit.
+
+## Flow Override
+
+[ref:.allhands/harness/src/lib/tmux.ts:ProfileSpawnConfig:553666b] accepts an optional `flowOverride` field. When provided, it takes precedence over the profile's default flow path in the resulting `SpawnConfig`:
+
+```
+flowPath = config.flowOverride || invocation.flowPath
+```
+
+This enables **type-routed spawning**: the TUI's New Initiative action selects a spec type, looks up the corresponding scoping flow via [ref:.allhands/harness/src/commands/tui.ts:SCOPING_FLOW_MAP:4ca2008], and passes it as `flowOverride` to the ideation agent profile. The same agent profile serves all initiative types -- only the flow changes.
+
+For milestone spec type, `flowOverride` is `undefined` (profile default flow is used). All other spec types resolve to a dedicated scoping flow file (e.g., `INVESTIGATION_SCOPING.md`, `REFACTOR_SCOPING.md`).
+
+## Template Context Resolution
+
+[ref:.allhands/harness/src/lib/tmux.ts:buildTemplateContext:553666b] constructs the `TemplateContext` used for resolving `${VAR_NAME}` placeholders in agent profile message templates. It resolves variables from the current git state, planning paths, spec metadata, and project settings:
+
+| Variable | Resolution Source |
+|----------|-------------------|
+| `BRANCH` | Current git branch via `getCurrentBranch()` |
+| `PLANNING_FOLDER` | `.planning/{branch}` root directory |
+| `PROMPTS_FOLDER` | `.planning/{branch}/prompts/` |
+| `ALIGNMENT_PATH` | `.planning/{branch}/alignment.md` |
+| `OUTPUT_PATH` | `.planning/{branch}/e2e-test-plan.md` |
+| `SPEC_NAME` | Display name from status, or planning key |
+| `SPEC_PATH` | Read from `status.yaml` spec field |
+| `SPEC_TYPE` | Spec frontmatter type via `getSpecForBranch()`, defaults to `'milestone'` |
+| `PROMPT_NUMBER` | Zero-padded two-digit number (when prompt-scoped) |
+| `PROMPT_PATH` | Absolute path to prompt file (when prompt-scoped) |
+| `HYPOTHESIS_DOMAINS` | Comma-separated list from [ref:.allhands/harness/src/hooks/shared.ts:EmergentSettings:ca0caaf] in `settings.json`, defaulting to `testing, stability, performance, feature, ux, integration` |
+
+`SPEC_TYPE` is resolved by reading the spec file's frontmatter `type` field for the current branch. This enables type-aware agent behavior -- agents can tailor their approach based on whether the initiative is a milestone, investigation, refactor, etc.
+
+`HYPOTHESIS_DOMAINS` is read from the `emergent.hypothesisDomains` array in `.allhands/settings.json` and joined with commas for template injection.
+
+## EmergentSettings
+
+[ref:.allhands/harness/src/hooks/shared.ts:EmergentSettings:ca0caaf] is the TypeScript interface for the `emergent` section of `.allhands/settings.json`:
+
+| Field | Type | Default | Purpose |
+|-------|------|---------|---------|
+| `hypothesisDomains` | `string[]` | `["testing", "stability", "performance", "feature", "ux", "integration"]` | Pool of domains the emergent planner diversifies across when generating hypothesis prompts |
+
+The settings schema is defined in [ref:.allhands/harness/src/schemas/settings.schema.json::77942b7]. The `emergent` object replaces the removed workflow YAML configuration system -- hypothesis domains are now centralized in project settings rather than per-workflow YAML files.
+
+## Window Naming and Prompt Scoping
+
+Window naming determines agent identity and concurrency rules:
+
+- **Non-prompt-scoped agents** (planner, coordinator): Window name = agent name. Only one instance allowed. [ref:.allhands/harness/src/lib/tmux.ts:buildWindowName:553666b] throws if a window with that name already exists.
+- **Prompt-scoped agents** (executor): Window name = `{name}-{promptNumber:02d}` (e.g., `executor-01`). Multiple concurrent instances allowed, one per prompt. Existing windows are killed and recreated on re-spawn.
+
+## Environment Variable Propagation
+
+[ref:.allhands/harness/src/lib/tmux.ts:buildAgentEnv:553666b] constructs the environment for each spawned agent:
+
+| Variable | Source | Purpose |
+|----------|--------|---------|
+| AGENT_ID | Window name | MCP daemon socket isolation, trace attribution |
+| AGENT_TYPE | Profile name | Agent role identification |
+| BRANCH | Current git branch | Branch context for operations |
+| PROMPT_NUMBER | SpawnConfig (if prompt-scoped) | Prompt tracking |
+| SPEC_NAME | SpawnConfig | Spec context |
+| PROMPT_SCOPED | "true" if applicable | Signals prompt-scoped behavior |
+| CLAUDE_AUTOCOMPACT_PCT_OVERRIDE | Project settings | Configurable autocompact threshold for prompt-scoped agents |
+| PYENV_REHASH_SKIP | Always "1" | Avoids lock contention when spawning multiple agents |
+
+## Session Management
+
+The tmux session layer handles multi-agent coordination through a standardized session named `ah-hub`.
+
+[ref:.allhands/harness/src/lib/tmux.ts:setupTUISession:553666b] orchestrates session setup with this decision tree:
+
+- **Not in tmux** --> Create new session, rename to `ah-hub`
+- **In tmux, multiple windows** --> Prompt user: create new session or reuse current
+- **In tmux, single window** --> Reuse current session, rename to `ah-hub`
+
+[ref:.allhands/harness/src/lib/tmux.ts:getSessionDecision:553666b] encodes this logic as a pure function returning `'create-new' | 'use-current' | 'no-prompt-needed'`.
+
+## Persistent Session State
+
+[ref:.allhands/harness/src/lib/session.ts::d831d20] persists session state to `.allhands/harness/.cache/session.json` (not git-tracked). This enables cross-process visibility into which agents are running.
+
+The state tracks two things:
+- **hub_window_id**: The tmux window ID where the TUI runs ([ref:.allhands/harness/src/lib/session.ts:setHubWindowId:d831d20])
+- **spawned_windows**: List of agent window names ([ref:.allhands/harness/src/lib/session.ts:addSpawnedWindow:d831d20], [ref:.allhands/harness/src/lib/session.ts:removeSpawnedWindow:d831d20])
+
+All mutations go through [ref:.allhands/harness/src/lib/session.ts:withSessionLock:d831d20], which uses `proper-lockfile` for cross-process file locking to prevent race conditions when multiple agents modify session state simultaneously.
+
+## Launcher Script Pattern
+
+Rather than constructing complex shell commands with escaping issues, the spawn system writes a temporary bash launcher script per agent. This script:
+
+1. Exports all environment variables
+2. Reads the combined prompt from a separate file (flow content + preamble + base branch info)
+3. Invokes `claude --settings .claude/settings.json --dangerously-skip-permissions` with the prompt
+4. Uses `exec bash` so the shell process is replaced, ensuring the window closes when claude exits
+
+Old launcher scripts (>24 hours) are cleaned up automatically by [ref:.allhands/harness/src/lib/tmux.ts:cleanupOldLaunchers:553666b].

package/docs/harness/cli/specs-command.md

@@ -0,0 +1,102 @@
+---
+description: "Spec file lifecycle management: listing by domain, status transitions between roadmap/in-progress/completed, branch-spec linking, and knowledge reindexing on spec moves."
+---
+
+# Specs Command
+
+## Intent
+
+Specs are the units of planned work in the harness. They live as markdown files with YAML frontmatter, organized into directories by lifecycle stage. The specs command manages the transitions between these stages, maintains the link between specs and git branches, and keeps knowledge indexes consistent when files move.
+
+## Spec File Organization
+
+```mermaid
+flowchart LR
+    subgraph "specs/"
+        Root["Active specs<br/>(in_progress)"]
+        subgraph "roadmap/"
+            Planned["Planned specs<br/>(roadmap)"]
+        end
+        subgraph "completed/"
+            Done["Completed specs<br/>(completed)"]
+        end
+    end
+```
+
+Each spec file (`*.spec.md` or `*.md`) contains frontmatter with:
+
+| Field | Type | Purpose |
+|-------|------|---------|
+| `name` | string | Spec identifier |
+| `domain_name` | string | Grouping domain (e.g., `harness`, `tui`) |
+| `status` | enum | `roadmap`, `in_progress`, or `completed` |
+| `dependencies` | string[] | Other spec names this depends on |
+| `branch` | string | Source of truth for which git branch implements this spec |
+
+## Spec Discovery
+
+Two discovery implementations exist for different contexts:
+
+**Library layer** ([ref:.allhands/harness/src/lib/specs.ts:loadAllSpecs:ce6f7c5]): Scans `specs/roadmap/`, `specs/`, and `specs/completed/` directories. Returns specs grouped by category with full metadata including title extraction from H1 headings via [ref:.allhands/harness/src/lib/specs.ts:extractTitle:ce6f7c5].
+
+**Command layer** ([ref:.allhands/harness/src/commands/specs.ts:loadAllSpecs:6d7289a]): Scans `specs/` and `specs/roadmap/` for `.spec.md` files specifically. Used by CLI subcommands for listing and status changes.
+
+## Branch-Spec Linking
+
+The `branch` field in spec frontmatter is the source of truth for which branch implements a spec. Two lookup functions serve different use cases:
+
+- [ref:.allhands/harness/src/lib/specs.ts:findSpecByBranch:ce6f7c5] -- strict match: scans all specs for one whose `branch` field matches the given branch name exactly
+- [ref:.allhands/harness/src/lib/specs.ts:getSpecForBranch:ce6f7c5] -- enhanced match: tries `findSpecByBranch` first, then falls back to initializing a planning directory if the branch has a spec assigned
+
+[ref:.allhands/harness/src/lib/specs.ts:findSpecById:ce6f7c5] provides ID-based lookup, searching across all category groups.
+
+## CLI Subcommands
+
+### `ah specs list`
+
+Lists all specs grouped by `domain_name`. Supports filtering:
+
+| Flag | Effect |
+|------|--------|
+| `--roadmap` | Only roadmap status specs |
+| `--completed` | Only completed specs |
+| `--in-progress` | Only in-progress specs |
+| `--domain <name>` | Filter to a single domain |
+| `--domains-only` | Just list domain names |
+
+### `ah specs current`
+
+Shows the spec linked to the current git branch. Uses [ref:.allhands/harness/src/lib/specs.ts:getSpecForBranch:ce6f7c5] with the current branch to display spec ID, title, path, domain, status, and dependencies.
+
+### `ah specs complete <name>`
+
+Marks a spec as completed:
+
+1. Finds the spec by name via [ref:.allhands/harness/src/commands/specs.ts:findSpecByName:6d7289a]
+2. Updates frontmatter status to `completed` via [ref:.allhands/harness/src/commands/specs.ts:updateSpecStatus:6d7289a]
+3. If the spec was in `specs/roadmap/`, moves it to `specs/`
+4. Triggers knowledge reindexing via [ref:.allhands/harness/src/commands/specs.ts:reindexAfterMove:6d7289a]
+
+### `ah specs resurrect <name>`
+
+Reverses completion -- moves a spec back to `specs/roadmap/` and sets status to `roadmap`. Mirrors the `complete` flow in reverse, including knowledge reindexing.
+
+### `ah specs persist <path>`
+
+Creates a branch for a spec, updates the spec frontmatter with the branch name, and commits the spec file to the base branch. This is the entry point for turning a planned spec into active work.
+
+## Knowledge Reindexing on Move
+
+When specs move between directories (complete or resurrect), the knowledge indexes must be updated to reflect the new file paths. [ref:.allhands/harness/src/commands/specs.ts:reindexAfterMove:6d7289a] handles this:
+
+- If the old path was in `specs/roadmap/`, mark it as deleted in the `roadmap` index
+- If the new path is in `specs/roadmap/`, mark it as added in the `roadmap` index
+- Always update the `docs` index (which covers all of `specs/`) with a delete + add pair
+
+This ensures semantic search returns results with correct file paths immediately after a spec transitions.
+
+## TUI Integration
+
+[ref:.allhands/harness/src/lib/specs.ts:specsToModalItems:ce6f7c5] converts spec groups into a format suitable for TUI selection modals, with category headers and selectable items. When no specs exist, it provides a helpful message directing users to create spec files.
+
+[ref:.allhands/harness/src/lib/specs.ts:loadSpecsByDomain:ce6f7c5] groups specs by `domain_name` for domain-oriented views, sorting both domains and specs within each domain alphabetically.

package/docs/harness/cli/tools-command.md

@@ -0,0 +1,122 @@
+---
+description: "MCP tool system providing daemon-managed server sessions, tool discovery and invocation, and a convention-based server registry with auto-discovery from config files."
+---
+
+## Intent
+
+The tools system gives agents access to external capabilities (browser automation, file operations, custom tools) through the Model Context Protocol. The central design tension is **session lifecycle management**: MCP servers are expensive to start, so the system uses a per-agent daemon process that keeps server sessions alive between tool calls. This avoids the cold-start penalty while preventing resource leaks through configurable timeouts.
+
+## Architecture
+
+```mermaid
+flowchart TB
+    subgraph CLI["CLI Layer"]
+        tools["ah tools <server>:<tool> args"]
+        list["ah tools list"]
+        servers["ah tools servers"]
+        shutdown["ah tools shutdown"]
+    end
+
+    subgraph Client["mcp-client.ts"]
+        callTool["callTool"]
+        discoverTools["discoverTools"]
+        sendToDaemon["sendToDaemon"]
+        startDaemon["startDaemon"]
+    end
+
+    subgraph Daemon["mcp-daemon.ts (per-agent process)"]
+        processCmd["processCommand"]
+        sessions["Session Map"]
+        timeout["checkSessionTimeouts"]
+    end
+
+    subgraph Registry["mcp/index.ts"]
+        discover["discoverServers"]
+        configs["Server Configs (.ts files)"]
+    end
+
+    subgraph Servers["MCP Servers"]
+        playwright["Playwright"]
+        filesystem["Filesystem"]
+        custom["Custom servers..."]
+    end
+
+    tools --> callTool
+    list --> discoverTools
+    servers --> discover
+    shutdown --> sendToDaemon
+
+    callTool --> sendToDaemon
+    discoverTools --> sendToDaemon
+    sendToDaemon --> |Unix socket| processCmd
+    startDaemon --> Daemon
+
+    processCmd --> sessions
+    sessions --> Servers
+    timeout --> |idle cleanup| sessions
+
+    discover --> configs
+```
+
+## Daemon Lifecycle
+
+The daemon is a long-lived background process scoped to a single agent (identified by AGENT_ID). It manages MCP server sessions via a Unix domain socket.
+
+**Startup**: [ref:.allhands/harness/src/lib/mcp-client.ts:startDaemon:50bc6e5] spawns the daemon as a detached child process. The daemon writes its PID and creates the socket at a path derived from the agent ID.
+
+**Communication**: [ref:.allhands/harness/src/lib/mcp-client.ts:sendToDaemon:50bc6e5] connects to the Unix socket and sends newline-delimited JSON commands. The daemon's [ref:.allhands/harness/src/lib/mcp-daemon.ts:handleConnection:263f999] buffers incoming data and dispatches complete messages to [ref:.allhands/harness/src/lib/mcp-daemon.ts:processCommand:263f999].
+
+**Session management**: Each MCP server gets a session (client + transport) created on first use via [ref:.allhands/harness/src/lib/mcp-daemon.ts:ensureSession:263f999]. Sessions track `lastUsedAt` timestamps and are reaped by [ref:.allhands/harness/src/lib/mcp-daemon.ts:checkSessionTimeouts:263f999] when idle beyond their configured timeout.
+
+**Shutdown**: [ref:.allhands/harness/src/lib/mcp-daemon.ts:gracefulShutdown:263f999] closes all MCP transports, clears sessions, closes the server socket, and cleans up PID/socket files. The daemon also exits when its last session closes.
+
+## Daemon Command Protocol
+
+| Command | Handler | Behavior |
+|---------|---------|----------|
+| `call` | [ref:.allhands/harness/src/lib/mcp-daemon.ts:handleCall:263f999] | Auto-starts session, invokes tool, returns result |
+| `discover` | [ref:.allhands/harness/src/lib/mcp-daemon.ts:handleDiscover:263f999] | Lists available tools (filters hiddenTools), caches per session |
+| `restart` | [ref:.allhands/harness/src/lib/mcp-daemon.ts:handleRestart:263f999] | Closes existing session, creates fresh one |
+| `list` | [ref:.allhands/harness/src/lib/mcp-daemon.ts:handleList:263f999] | Returns all active sessions with timing info |
+| `ping` | [ref:.allhands/harness/src/lib/mcp-daemon.ts:handlePing:263f999] | Refreshes all session timestamps (keepalive) |
+| `info` | N/A | Returns PID, session count, session names |
+| `shutdown` | N/A | Graceful shutdown of all sessions and daemon |
+
+## Server Registry
+
+[ref:.allhands/harness/src/mcp/index.ts:discoverServers:55a5a7f] auto-discovers server configurations by scanning `.ts` files in the `mcp/` directory (excluding `index.ts` and `_template.ts`). Each file exports a `config` object of type `McpServerConfig`.
+
+Key config fields that shape behavior:
+
+| Field | Effect |
+|-------|--------|
+| `stateful` | If true, daemon keeps session alive between calls. If false, one-shot connections |
+| `stateful_session_timeout` | Custom idle timeout (default from `DAEMON_DEFAULT_MCP_TIMEOUT`) |
+| `hiddenTools` | Tool names to exclude from discovery results |
+| `toolHints` | Extra usage hints shown in `--help` output |
+
+Built-in servers: [ref:.allhands/harness/src/mcp/filesystem.ts::1d8cb8a] (stateless file operations) and [ref:.allhands/harness/src/mcp/playwright.ts::98edc6a] (stateful browser automation). New servers are added by copying [ref:.allhands/harness/src/mcp/_template.ts::2919984].
+
+## Runtime Layer
+
+[ref:.allhands/harness/src/lib/mcp-runtime.ts::f359acf] provides shared utilities used by both daemon and one-shot paths:
+
+- [ref:.allhands/harness/src/lib/mcp-runtime.ts:buildServerCommand:f359acf] resolves the command array from config, handling `npx`, `uvx`, and direct binary paths
+- [ref:.allhands/harness/src/lib/mcp-runtime.ts:resolveEnvVars:f359acf] interpolates `${VAR_NAME}` patterns in environment config from the process environment
+- [ref:.allhands/harness/src/lib/mcp-runtime.ts:formatToolHelp:f359acf] generates human-readable help text for tools including parameter schemas and hints
+- Tool discovery results are cached to disk per server ([ref:.allhands/harness/src/lib/mcp-runtime.ts:getToolsWithCache:f359acf]) to avoid repeated cold starts for tool listing
+
+## CLI Surface
+
+[ref:.allhands/harness/src/commands/tools.ts:register:dbc48c6] exposes these subcommands:
+
+- `ah tools <server>:<tool> [args...]` -- Invoke a tool with key=value arguments ([ref:.allhands/harness/src/commands/tools.ts:parseToolArgs:dbc48c6] handles JSON auto-parsing)
+- `ah tools list [server]` -- List tools for a server ([ref:.allhands/harness/src/commands/tools.ts:handleListTools:dbc48c6])
+- `ah tools servers` -- List all available servers with session status ([ref:.allhands/harness/src/commands/tools.ts:handleListServers:dbc48c6])
+- `ah tools sessions` -- Show active daemon sessions ([ref:.allhands/harness/src/commands/tools.ts:handleListSessions:dbc48c6])
+- `ah tools shutdown` -- Shut down the daemon ([ref:.allhands/harness/src/commands/tools.ts:handleShutdownDaemon:dbc48c6])
+- `ah tools restart <server>` -- Restart a server session ([ref:.allhands/harness/src/commands/tools.ts:handleSessionRestart:dbc48c6])
+
+## One-Shot vs Daemon Path
+
+The client layer ([ref:.allhands/harness/src/lib/mcp-client.ts::50bc6e5]) transparently routes through the daemon when running or falls back to one-shot connections via [ref:.allhands/harness/src/lib/mcp-client.ts:createOneShot:50bc6e5]. This dual-path design means tools work even without the daemon, at the cost of cold-starting the server each time.