@ag-eco/agentplate-cli 0.13.0

package/src/types.ts

@@ -0,0 +1,970 @@
+// === Model & Provider Types ===
+
+/** Backward-compatible model alias for Anthropic models. */
+export type ModelAlias = "sonnet" | "opus" | "haiku";
+
+/**
+ * A model reference: either a simple alias ('sonnet') or a provider-qualified
+ * string ('provider/model', e.g. 'openrouter/openai/gpt-5.3').
+ */
+export type ModelRef = ModelAlias | (string & {});
+
+/** Configuration for a model provider. */
+export interface ProviderConfig {
+	type: "native" | "gateway";
+	baseUrl?: string;
+	authTokenEnv?: string;
+}
+
+/** Resolved model with optional provider environment variables. */
+export interface ResolvedModel {
+	model: string;
+	env?: Record<string, string>;
+	/** True when the model was explicitly set via config.models[capability]. */
+	isExplicitOverride?: boolean;
+}
+
+/** Configuration for the Pi runtime's model alias expansion. */
+export interface PiRuntimeConfig {
+	/** Provider prefix for unqualified model aliases (e.g., "anthropic", "amazon-bedrock"). */
+	provider: string;
+	/** Maps short aliases (e.g., "opus") to provider-qualified model IDs. */
+	modelMap: Record<string, string>;
+}
+
+// === Task Tracker ===
+
+/** Backend for the task tracker. Defined here for use in AgentplateConfig. */
+export type TaskTrackerBackend = "auto" | "sprout" | "beads";
+
+// === Project Configuration ===
+
+/**
+ * Conditions that trigger automatic coordinator shutdown.
+ * All triggers default to false for backward compatibility.
+ */
+export interface CoordinatorExitTriggers {
+	/** Exit when all spawned agents have completed and their branches have been merged. */
+	allAgentsDone: boolean;
+	/** Exit when the task tracker reports no unblocked work (sr/bd ready returns empty). */
+	taskTrackerEmpty: boolean;
+	/** Exit when a typed shutdown mail is received from an external caller (e.g., greenhouse). */
+	onShutdownSignal: boolean;
+}
+
+/** A single quality gate command that agents must pass before reporting completion. */
+export interface QualityGate {
+	/** Display name shown in the overlay (e.g., "Tests"). */
+	name: string;
+	/** Shell command to run (e.g., "bun test"). */
+	command: string;
+	/** Human-readable description of what passing means (e.g., "all tests must pass"). */
+	description: string;
+}
+
+export interface AgentplateConfig {
+	project: {
+		name: string;
+		root: string; // Absolute path to target repo
+		canonicalBranch: string; // "main" | "develop"
+		qualityGates?: QualityGate[];
+		/** Default trellis profile name. Used when --profile is not explicitly passed to sling/coordinator. */
+		defaultProfile?: string;
+	};
+	agents: {
+		manifestPath: string; // Path to agent-manifest.json
+		baseDir: string; // Path to base agent definitions
+		maxConcurrent: number; // Rate limit ceiling
+		staggerDelayMs: number; // Delay between spawns
+		maxDepth: number; // Hierarchy depth limit (default 2)
+		maxSessionsPerRun: number; // Max total sessions per run (0 = unlimited)
+		maxAgentsPerLead: number; // Max children a single lead can spawn (0 = unlimited)
+	};
+	worktrees: {
+		baseDir: string; // Where worktrees live
+	};
+	taskTracker: {
+		backend: TaskTrackerBackend; // "auto" | "sprout" | "beads"
+		enabled: boolean;
+	};
+	loam: {
+		enabled: boolean;
+		domains: string[]; // Domains to prime (empty = auto-detect)
+		primeFormat: "markdown" | "xml" | "json";
+	};
+	merge: {
+		aiResolveEnabled: boolean;
+		reimagineEnabled: boolean;
+	};
+	providers: Record<string, ProviderConfig>;
+	watchdog: {
+		tier0Enabled: boolean; // Tier 0: Mechanical daemon (heartbeat, tmux/pid liveness)
+		tier0IntervalMs: number; // Default 30_000
+		tier1Enabled: boolean; // Tier 1: Triage agent (ephemeral AI analysis)
+		tier2Enabled: boolean; // Tier 2: Monitor agent (continuous patrol)
+		staleThresholdMs: number; // When to consider agent stale
+		zombieThresholdMs: number; // When to kill
+		nudgeIntervalMs: number; // Time between progressive nudge stages (default 60_000)
+		rpcTimeoutMs?: number; // Timeout for RPC getState() calls (default 5_000)
+		triageTimeoutMs?: number; // Timeout for Tier 1 AI triage calls (default 30_000)
+		maxEscalationLevel?: number; // Maximum escalation level before termination (default 3)
+		notifyParentOnDeath?: boolean; // Send synthetic worker_died mail to parent on watchdog termination (default true)
+	};
+	models: Partial<Record<string, ModelRef>>;
+	logging: {
+		verbose: boolean;
+		redactSecrets: boolean;
+	};
+	coordinator?: {
+		/** Conditions that trigger automatic coordinator shutdown. */
+		exitTriggers: CoordinatorExitTriggers;
+	};
+	runtime?: {
+		/** Default runtime adapter name (default: "claude"). */
+		default: string;
+		/**
+		 * Per-capability runtime overrides. Maps capability names (e.g. "coordinator", "builder")
+		 * to runtime adapter names. Lookup chain: explicit --runtime flag > capabilities[cap] > default > "claude".
+		 */
+		capabilities?: Partial<Record<string, string>>;
+		/**
+		 * Runtime adapter for headless one-shot AI calls (--print mode).
+		 * Used by merge/resolver.ts and watchdog/triage.ts.
+		 * Falls back to runtime.default when omitted.
+		 */
+		printCommand?: string;
+		/** Pi runtime configuration for model alias expansion. */
+		pi?: PiRuntimeConfig;
+		/**
+		 * Delay in milliseconds between creating a tmux session and polling
+		 * for TUI readiness. Gives slow shells (oh-my-zsh, starship, etc.)
+		 * time to finish initializing before the agent command starts.
+		 * Default: 0 (no delay).
+		 */
+		shellInitDelayMs?: number;
+		/**
+		 * Project-level default for spawning Claude Code agents in headless mode
+		 * (Bun.spawn + stream-json) instead of the tmux interactive runtime.
+		 * Per-spawn `--headless` / `--no-headless` flags on `ap sling` override this.
+		 * Default: false (tmux).
+		 */
+		claudeHeadlessByDefault?: boolean;
+	};
+}
+
+// === Agent Manifest ===
+
+export interface AgentManifest {
+	version: string;
+	agents: Record<string, AgentDefinition>;
+	capabilityIndex: Record<string, string[]>;
+}
+
+export interface AgentDefinition {
+	file: string; // Path to base agent definition (.md)
+	model: ModelRef;
+	tools: string[]; // Allowed tools
+	capabilities: string[]; // What this agent can do
+	canSpawn: boolean; // Can this agent spawn sub-workers?
+	constraints: string[]; // Machine-readable restrictions
+}
+
+/** All valid agent capability types. Used for compile-time validation. */
+export const SUPPORTED_CAPABILITIES = [
+	"scout",
+	"builder",
+	"reviewer",
+	"lead",
+	"merger",
+	"orchestrator",
+	"coordinator",
+	"supervisor",
+	"monitor",
+] as const;
+
+/** Union type derived from the capabilities constant. */
+export type Capability = (typeof SUPPORTED_CAPABILITIES)[number];
+
+// === Agent Session ===
+
+/**
+ * Agent lifecycle states.
+ *
+ * `in_turn` and `between_turns` are spawn-per-turn-specific substates that
+ * split the legacy `working` state so the UI can distinguish a worker actively
+ * executing a turn from one idling between mail batches (agentplate-3087):
+ *
+ *   - `in_turn`: the turn-runner has observed at least one parser event from
+ *     a live claude subprocess. The agent is mid-execution.
+ *   - `between_turns`: the turn-runner finished a turn without a terminal
+ *     mail; the agent is alive (process gone, session pinned) and waiting
+ *     for the next mail batch to spawn a fresh turn.
+ *
+ * `working` remains the active state for tmux/long-lived headless agents
+ * (coordinator, orchestrator, monitor, sapling) which have no per-turn
+ * boundary. Spawn-per-turn workers (builder/scout/reviewer/lead/merger
+ * under the headless default) transition through in_turn ↔ between_turns
+ * instead.
+ */
+export type AgentState =
+	| "booting"
+	| "working"
+	| "in_turn"
+	| "between_turns"
+	| "completed"
+	| "stalled"
+	| "zombie";
+
+/**
+ * Result of a guarded state transition attempt (`SessionStore.tryTransitionState`).
+ *
+ * Discriminated by `ok`. When `ok` is false, `reason` distinguishes:
+ *   - `not_found`: no session exists for the given name.
+ *   - `illegal_transition`: a session exists but the matrix forbids prev → attempted.
+ *
+ * `prev` is always the state observed by the SQL CAS. For `illegal_transition` it
+ * is the state that blocked the write (which may differ from what the caller read,
+ * if another writer landed first).
+ */
+export type TransitionOutcome =
+	| { ok: true; prev: AgentState; next: AgentState }
+	| { ok: false; reason: "not_found"; attempted: AgentState }
+	| { ok: false; reason: "illegal_transition"; prev: AgentState; attempted: AgentState };
+
+export interface AgentSession {
+	id: string; // Unique session ID
+	agentName: string; // Unique per-session name
+	capability: string; // Which agent definition
+	worktreePath: string;
+	branchName: string;
+	taskId: string; // Task being worked
+	tmuxSession: string; // Tmux session name
+	state: AgentState;
+	pid: number | null; // Claude Code PID
+	parentAgent: string | null; // Who spawned this agent (null = orchestrator)
+	depth: number; // 0 = direct from orchestrator
+	runId: string | null; // Groups sessions in the same orchestrator run
+	startedAt: string;
+	lastActivity: string;
+	escalationLevel: number; // Progressive nudge stage: 0=warn, 1=nudge, 2=escalate, 3=terminate
+	stalledSince: string | null; // ISO timestamp when agent first entered stalled state
+	transcriptPath: string | null; // Runtime-provided transcript JSONL path (decoupled from ~/.claude/)
+	promptVersion?: string | null; // Trellis prompt version used at sling time (e.g. "builder@17")
+	claudeSessionId?: string | null; // Runtime-provided session_id (Claude stream-json), eagerly pinned on first event
+}
+
+// === Agent Identity ===
+
+export interface AgentIdentity {
+	name: string;
+	capability: string;
+	created: string;
+	sessionsCompleted: number;
+	expertiseDomains: string[];
+	recentTasks: Array<{
+		taskId: string;
+		summary: string;
+		completedAt: string;
+	}>;
+}
+
+// === Mail (Custom SQLite) ===
+
+/** Semantic message types (original, human-readable). */
+export type MailSemanticType = "status" | "question" | "result" | "error";
+
+/** Protocol message types for structured agent coordination. */
+export type MailProtocolType =
+	| "worker_done"
+	| "worker_died"
+	| "merge_ready"
+	| "merged"
+	| "merge_failed"
+	| "escalation"
+	| "health_check"
+	| "dispatch"
+	| "assign"
+	| "decision_gate";
+
+/** All valid mail message types. */
+export type MailMessageType = MailSemanticType | MailProtocolType;
+
+/** All protocol type strings as a runtime array for CHECK constraint generation. */
+export const MAIL_MESSAGE_TYPES: readonly MailMessageType[] = [
+	"status",
+	"question",
+	"result",
+	"error",
+	"worker_done",
+	"worker_died",
+	"merge_ready",
+	"merged",
+	"merge_failed",
+	"escalation",
+	"health_check",
+	"dispatch",
+	"assign",
+	"decision_gate",
+] as const;
+
+export interface MailMessage {
+	id: string; // "msg-" + nanoid(12)
+	from: string; // Agent name
+	to: string; // Agent name or "orchestrator"
+	subject: string;
+	body: string;
+	priority: "low" | "normal" | "high" | "urgent";
+	type: MailMessageType;
+	threadId: string | null; // Conversation threading
+	payload: string | null; // JSON-encoded structured data for protocol messages
+	read: boolean;
+	createdAt: string; // ISO timestamp
+}
+
+// === Mail Protocol Payloads ===
+
+/** Worker signals task completion to supervisor. */
+export interface WorkerDonePayload {
+	taskId: string;
+	branch: string;
+	exitCode: number;
+	filesModified: string[];
+}
+
+/**
+ * Watchdog signals the parent that one of its children was terminated.
+ *
+ * Synthetic mail injected by the Tier 0 daemon when it transitions a worker
+ * to `zombie` (agentplate-c111). Without this, the parent — typically a lead
+ * waiting for `worker_done` from this child — would block indefinitely on
+ * mail that will never arrive. The parent reads this on its next mail-injector
+ * tick and decides whether to retry, escalate, or report up.
+ */
+export interface WorkerDiedPayload {
+	agentName: string;
+	capability: string;
+	taskId: string;
+	/** Reason the watchdog or runner terminated the child (e.g. "Process terminated"). */
+	reason: string;
+	/** ISO timestamp of the child's last observed activity. */
+	lastActivity: string;
+	/**
+	 * Source that detected the failure.
+	 * - `tier0`/`tier1`: watchdog daemon detected a dead/stuck process out-of-band.
+	 * - `runner`: the per-turn runner observed an in-band failure — either an
+	 *   abort/stall that forced SIGTERM/SIGKILL, or a clean exit without the
+	 *   capability's terminal mail (silent-no-op, agentplate-4159 / agentplate-c772).
+	 */
+	terminatedBy: "tier0" | "tier1" | "runner";
+}
+
+/** Supervisor signals branch is verified and ready for merge. */
+export interface MergeReadyPayload {
+	branch: string;
+	taskId: string;
+	agentName: string;
+	filesModified: string[];
+}
+
+/** Merger signals branch was merged successfully. */
+export interface MergedPayload {
+	branch: string;
+	taskId: string;
+	tier: ResolutionTier;
+}
+
+/** Merger signals merge failed, needs rework. */
+export interface MergeFailedPayload {
+	branch: string;
+	taskId: string;
+	conflictFiles: string[];
+	errorMessage: string;
+}
+
+/** Any agent escalates an issue to a higher-level decision-maker. */
+export interface EscalationPayload {
+	severity: "warning" | "error" | "critical";
+	taskId: string | null;
+	context: string;
+}
+
+/** Watchdog probes agent liveness. */
+export interface HealthCheckPayload {
+	agentName: string;
+	checkType: "liveness" | "readiness";
+}
+
+/** Coordinator dispatches work to a supervisor. */
+export interface DispatchPayload {
+	taskId: string;
+	specPath: string;
+	capability: Capability;
+	fileScope: string[];
+	/** Optional: skip scout phase for lead agents */
+	skipScouts?: boolean;
+	/** Optional: skip review phase for lead agents */
+	skipReview?: boolean;
+	/** Optional: per-lead max agent ceiling override */
+	maxAgents?: number;
+}
+
+/** Supervisor assigns work to a specific worker. */
+export interface AssignPayload {
+	taskId: string;
+	specPath: string;
+	workerName: string;
+	branch: string;
+}
+
+/** Agent pauses for a human-in-the-loop decision before proceeding. */
+export interface DecisionGatePayload {
+	/** Options for the human decision-maker to choose from. */
+	options: string[];
+	/** Context explaining why the decision is needed. */
+	context: string;
+	/** Optional deadline for the decision (ISO timestamp). */
+	deadline?: string;
+}
+
+/** Maps protocol message types to their payload interfaces. */
+export interface MailPayloadMap {
+	worker_done: WorkerDonePayload;
+	worker_died: WorkerDiedPayload;
+	merge_ready: MergeReadyPayload;
+	merged: MergedPayload;
+	merge_failed: MergeFailedPayload;
+	escalation: EscalationPayload;
+	health_check: HealthCheckPayload;
+	dispatch: DispatchPayload;
+	assign: AssignPayload;
+	decision_gate: DecisionGatePayload;
+}
+
+// === Overlay ===
+
+export interface OverlayConfig {
+	agentName: string;
+	taskId: string;
+	specPath: string | null;
+	branchName: string;
+	worktreePath: string;
+	fileScope: string[];
+	loamDomains: string[];
+	parentAgent: string | null;
+	depth: number;
+	canSpawn: boolean;
+	capability: string;
+	/** Full content of the base agent definition file (Layer 1: role-specific HOW). */
+	baseDefinition: string;
+	/** Rendered profile content from trellis (Layer 2: deployment-specific WHAT KIND). Inserted between base definition and assignment. */
+	profileContent?: string;
+	/** Pre-fetched loam expertise output to embed directly in the overlay. */
+	loamExpertise?: string;
+	/** When true, lead agents should skip Phase 1 (scout) and go straight to Phase 2 (build). */
+	skipScout?: boolean;
+	/** When true, lead agents should skip Phase 3 review and self-verify instead. */
+	skipReview?: boolean;
+	/** Per-lead max agents ceiling override from dispatch. Injected into overlay for lead visibility. */
+	maxAgentsOverride?: number;
+	trackerCli?: string; // "sr" or "bd"
+	trackerName?: string; // "sprout" or "beads"
+	/** Quality gate commands for the agent overlay. Falls back to defaults if undefined. */
+	qualityGates?: QualityGate[];
+	/** Relative path to the instruction file within the worktree (runtime-specific). Defaults to .claude/CLAUDE.md. */
+	instructionPath?: string;
+	/**
+	 * Names of sibling agents dispatched in parallel that may share file scope
+	 * with this agent. When set, the overlay renders a "Parallel Siblings"
+	 * section with rebase-before-merge_ready guidance (agentplate-f76a). Empty
+	 * or unset → no overlay section.
+	 */
+	siblings?: string[];
+}
+
+// === Merge Queue ===
+
+export type ResolutionTier = "clean-merge" | "auto-resolve" | "ai-resolve" | "reimagine";
+
+export interface MergeEntry {
+	branchName: string;
+	taskId: string;
+	agentName: string;
+	filesModified: string[];
+	enqueuedAt: string;
+	status: "pending" | "merging" | "merged" | "conflict" | "failed";
+	resolvedTier: ResolutionTier | null;
+}
+
+export interface MergeResult {
+	entry: MergeEntry;
+	success: boolean;
+	tier: ResolutionTier;
+	conflictFiles: string[];
+	errorMessage: string | null;
+	/** Warnings about files where auto-resolve was skipped to prevent content loss. */
+	warnings: string[];
+}
+
+/** Parsed conflict pattern from a single loam record. */
+export interface ParsedConflictPattern {
+	tier: ResolutionTier;
+	success: boolean;
+	files: string[];
+	agent: string;
+	branch: string;
+}
+
+/** Historical conflict data assembled from loam search results. */
+export interface ConflictHistory {
+	/** Tiers to skip based on historical failure rates for these files. */
+	skipTiers: ResolutionTier[];
+	/** Descriptions of past successful resolutions for AI prompt enrichment. */
+	pastResolutions: string[];
+	/** Files predicted to conflict based on historical patterns. */
+	predictedConflictFiles: string[];
+}
+
+/**
+ * Side-effect-free prediction of how `ap merge` would resolve a branch.
+ * Produced by `predictConflicts` (src/merge/predict.ts) without touching HEAD,
+ * the working tree, or the merge lock — surfaced via `ap merge --dry-run` so a
+ * lead/operator/greenhouse can branch on `wouldRequireAgent`.
+ */
+export interface ConflictPrediction {
+	/** The tier `ap merge` would land in if invoked now. */
+	predictedTier: ResolutionTier;
+	/** Files that would conflict — empty for clean-merge. */
+	conflictFiles: string[];
+	/** True iff predictedTier is "ai-resolve" or "reimagine" (Tier 3+). */
+	wouldRequireAgent: boolean;
+	/** Short, operator-readable explanation for the predicted tier. */
+	reason: string;
+}
+
+// === Watchdog ===
+
+export interface HealthCheck {
+	agentName: string;
+	timestamp: string;
+	processAlive: boolean;
+	tmuxAlive: boolean;
+	pidAlive: boolean | null; // null when pid is unavailable
+	lastActivity: string;
+	state: AgentState;
+	action: "none" | "escalate" | "terminate" | "investigate" | "complete";
+	/** Describes any conflict between observable state and recorded state. */
+	reconciliationNote: string | null;
+}
+
+// === Logging ===
+
+export interface LogEvent {
+	timestamp: string;
+	level: "debug" | "info" | "warn" | "error";
+	event: string;
+	agentName: string | null;
+	data: Record<string, unknown>;
+}
+
+// === Metrics ===
+
+export interface SessionMetrics {
+	agentName: string;
+	taskId: string;
+	capability: string;
+	startedAt: string;
+	completedAt: string | null;
+	durationMs: number;
+	exitCode: number | null;
+	mergeResult: ResolutionTier | null;
+	parentAgent: string | null;
+	inputTokens: number;
+	outputTokens: number;
+	cacheReadTokens: number;
+	cacheCreationTokens: number;
+	estimatedCostUsd: number | null;
+	modelUsed: string | null;
+	runId: string | null;
+}
+
+/** A point-in-time token usage snapshot for a running agent session. */
+export interface TokenSnapshot {
+	agentName: string;
+	inputTokens: number;
+	outputTokens: number;
+	cacheReadTokens: number;
+	cacheCreationTokens: number;
+	estimatedCostUsd: number | null;
+	modelUsed: string | null;
+	createdAt: string;
+	runId: string | null;
+}
+
+// === Task Groups (Batch Coordination) ===
+
+export interface TaskGroup {
+	id: string; // "group-" + nanoid(8)
+	name: string;
+	memberIssueIds: string[]; // beads issue IDs tracked by this group
+	status: "active" | "completed";
+	createdAt: string; // ISO timestamp
+	completedAt: string | null; // ISO timestamp when all members closed
+}
+
+export interface TaskGroupProgress {
+	group: TaskGroup;
+	total: number;
+	completed: number;
+	inProgress: number;
+	blocked: number;
+	open: number;
+}
+
+// === Event Store (Observability) ===
+
+/** Event types for agent activity tracking. */
+export type EventType =
+	| "tool_start"
+	| "tool_end"
+	| "session_start"
+	| "session_end"
+	| "mail_sent"
+	| "mail_received"
+	| "spawn"
+	| "error"
+	| "custom"
+	| "turn_start"
+	| "turn_end"
+	| "progress"
+	| "result";
+
+/** Severity levels for events. */
+export type EventLevel = "debug" | "info" | "warn" | "error";
+
+/** All valid event level strings as a runtime array for CHECK constraint generation. */
+export const EVENT_LEVELS: readonly EventLevel[] = ["debug", "info", "warn", "error"] as const;
+
+/** An event as stored in the SQLite events table. */
+export interface StoredEvent {
+	id: number;
+	runId: string | null;
+	agentName: string;
+	sessionId: string | null;
+	eventType: EventType;
+	toolName: string | null;
+	toolArgs: string | null;
+	toolDurationMs: number | null;
+	level: EventLevel;
+	data: string | null;
+	createdAt: string;
+}
+
+/** Input for inserting a new event (id and createdAt are auto-generated). */
+export type InsertEvent = Omit<StoredEvent, "id" | "createdAt">;
+
+/** Options for filtering event queries. */
+export interface EventQueryOptions {
+	limit?: number;
+	since?: string; // ISO timestamp
+	until?: string; // ISO timestamp
+	level?: EventLevel;
+}
+
+/** Tool usage statistics returned by getToolStats. */
+export interface ToolStats {
+	toolName: string;
+	count: number;
+	avgDurationMs: number;
+	maxDurationMs: number;
+}
+
+/** Interface for the SQLite-backed event store. */
+export interface EventStore {
+	/** Insert a new event. Returns the auto-generated row ID. */
+	insert(event: InsertEvent): number;
+	/** Find the most recent unmatched tool_start for correlation. Returns start ID and duration. */
+	correlateToolEnd(
+		agentName: string,
+		toolName: string,
+	): { startId: number; durationMs: number } | null;
+	/** Get events for a specific agent. */
+	getByAgent(agentName: string, opts?: EventQueryOptions): StoredEvent[];
+	/** Get events for a specific run. */
+	getByRun(runId: string, opts?: EventQueryOptions): StoredEvent[];
+	/** Get error-level events. */
+	getErrors(opts?: EventQueryOptions): StoredEvent[];
+	/** Get a timeline of events with required options. */
+	getTimeline(opts: EventQueryOptions & { since: string }): StoredEvent[];
+	/** Get aggregated tool usage statistics. */
+	getToolStats(opts?: { agentName?: string; since?: string }): ToolStats[];
+	/** Delete events matching criteria. Returns number of rows deleted. */
+	purge(opts: { all?: boolean; olderThanMs?: number; agentName?: string }): number;
+	/** Close the database connection. */
+	close(): void;
+}
+
+// === Run (Coordinator Session Grouping) ===
+
+/** Status of a run (coordinator session grouping agents). */
+export type RunStatus = "active" | "completed" | "failed";
+
+/** A run groups all agents spawned from one coordinator session. */
+export interface Run {
+	id: string; // Format: run-{ISO timestamp}
+	startedAt: string;
+	completedAt: string | null;
+	agentCount: number;
+	coordinatorSessionId: string | null;
+	coordinatorName: string | null; // which coordinator owns this run
+	status: RunStatus;
+}
+
+/** Input for creating a new run. */
+export type InsertRun = Omit<Run, "completedAt" | "agentCount" | "coordinatorName"> & {
+	agentCount?: number;
+	/** Which coordinator owns this run. Defaults to null when not provided. */
+	coordinatorName?: string | null;
+};
+
+/** Interface for run management operations. */
+export interface RunStore {
+	/** Create a new run. */
+	createRun(run: InsertRun): void;
+	/** Get a run by ID, or null if not found. */
+	getRun(id: string): Run | null;
+	/** Get the most recently started active run. */
+	getActiveRun(): Run | null;
+	/** Get the most recently started active run for a specific coordinator. */
+	getActiveRunForCoordinator(coordinatorName: string): Run | null;
+	/** List runs, optionally limited. */
+	listRuns(opts?: { limit?: number; status?: RunStatus }): Run[];
+	/** Increment agent count for a run. */
+	incrementAgentCount(runId: string): void;
+	/** Complete a run (set status and completedAt). */
+	completeRun(runId: string, status: "completed" | "failed"): void;
+	/** Close the store (if standalone — in practice may share DB with SessionStore). */
+	close(): void;
+}
+
+// === Loam CLI Results ===
+
+/** Loam status result (domain statistics). */
+export interface LoamStatus {
+	domains: Array<{ name: string; recordCount: number; lastUpdated: string }>;
+}
+
+/** Result from loam diff command. */
+export interface LoamDiffResult {
+	success: boolean;
+	command: string;
+	since: string;
+	domains: string[];
+	message: string;
+}
+
+/** Result from loam learn command. */
+export interface LoamLearnResult {
+	success: boolean;
+	command: string;
+	changedFiles: string[];
+	suggestedDomains: string[];
+	unmatchedFiles: string[];
+}
+
+/** Result from loam prune command. */
+export interface LoamPruneResult {
+	success: boolean;
+	command: string;
+	dryRun: boolean;
+	totalPruned: number;
+	results: Array<{
+		domain: string;
+		pruned: number;
+		records: string[];
+	}>;
+}
+
+/** Health check result from loam doctor. */
+export interface LoamDoctorResult {
+	success: boolean;
+	command: string;
+	checks: Array<{
+		name: string;
+		status: "pass" | "warn" | "fail";
+		message: string;
+		fixable: boolean;
+		details: string[];
+	}>;
+	summary: {
+		pass: number;
+		warn: number;
+		fail: number;
+	};
+}
+
+/** Ready records result from loam ready. */
+export interface LoamReadyResult {
+	success: boolean;
+	command: string;
+	count: number;
+	entries: Array<{
+		domain: string;
+		id: string;
+		type: string;
+		recorded_at: string;
+		summary: string;
+		record: Record<string, unknown>;
+	}>;
+}
+
+/** Result from loam compact command. */
+export interface LoamCompactResult {
+	success: boolean;
+	command: string;
+	action: string;
+	candidates?: Array<{
+		domain: string;
+		type: string;
+		records: Array<{
+			id: string;
+			summary: string;
+			recorded_at: string;
+		}>;
+	}>;
+	compacted?: Array<{
+		domain: string;
+		type: string;
+		before: number;
+		after: number;
+		recordIds: string[];
+	}>;
+	message?: string;
+}
+
+// === Trellis CLI Results ===
+
+/** A single section within a rendered trellis prompt. */
+export interface TrellisPromptSection {
+	name: string;
+	body: string;
+}
+
+/** Summary of a trellis prompt as returned by list/show. */
+export interface TrellisPromptSummary {
+	id: string;
+	name: string;
+	version: number;
+	sections: TrellisPromptSection[];
+}
+
+/** Result from tl render — resolved prompt with all inheritance applied. */
+export interface TrellisRenderResult {
+	success: boolean;
+	name: string;
+	version: number;
+	sections: TrellisPromptSection[];
+}
+
+/** Result from tl validate — validation status and errors. */
+export interface TrellisValidateResult {
+	success: boolean;
+	errors: string[];
+}
+
+/** Result from tl list — list of all prompts. */
+export interface TrellisListResult {
+	success: boolean;
+	prompts: TrellisPromptSummary[];
+}
+
+/** Result from tl show — single prompt record. */
+export interface TrellisShowResult {
+	success: boolean;
+	prompt: TrellisPromptSummary;
+}
+
+// === Session Lifecycle (Checkpoint / Handoff / Continuity) ===
+
+/**
+ * Snapshot of agent progress, saved before compaction or handoff.
+ * Stored as JSON in .agentplate/agents/{name}/checkpoint.json.
+ */
+export interface SessionCheckpoint {
+	agentName: string;
+	taskId: string;
+	sessionId: string; // The AgentSession.id that created this checkpoint
+	timestamp: string; // ISO
+	progressSummary: string; // Human-readable summary of work done so far
+	filesModified: string[]; // Paths modified since session start
+	currentBranch: string;
+	pendingWork: string; // What remains to be done
+	loamDomains: string[]; // Domains the agent has been working in
+}
+
+/**
+ * Record of a session handoff — when one session ends and another picks up.
+ */
+export interface SessionHandoff {
+	fromSessionId: string;
+	toSessionId: string | null; // null until the new session starts
+	checkpoint: SessionCheckpoint;
+	reason: "compaction" | "crash" | "manual" | "timeout";
+	handoffAt: string; // ISO timestamp
+}
+
+/**
+ * Three-layer model for agent persistence.
+ * Session = ephemeral Claude runtime
+ * Sandbox = git worktree (persists across sessions)
+ * Identity = permanent agent record (persists across assignments)
+ */
+export interface AgentLayers {
+	identity: AgentIdentity;
+	sandbox: {
+		worktreePath: string;
+		branchName: string;
+		taskId: string;
+	};
+	session: {
+		id: string;
+		pid: number | null;
+		tmuxSession: string;
+		startedAt: string;
+		checkpoint: SessionCheckpoint | null;
+	} | null; // null when sandbox exists but no active session
+}
+
+// === Session Insight Analysis ===
+
+/** A single structured insight extracted from a completed session. */
+export interface SessionInsight {
+	/** Loam record type for this insight. */
+	type: "pattern" | "convention" | "failure";
+	/** Loam domain this insight belongs to. */
+	domain: string;
+	/** Human-readable description of the insight. */
+	description: string;
+	/** Tags for loam record categorization. */
+	tags: string[];
+}
+
+/** Aggregated tool usage profile for a session. */
+export interface ToolProfile {
+	topTools: Array<{ name: string; count: number; avgMs: number }>;
+	totalToolCalls: number;
+	errorCount: number;
+}
+
+/** File edit frequency profile for a session. */
+export interface FileProfile {
+	/** Files edited more than once, sorted by edit count descending. */
+	hotFiles: Array<{ path: string; editCount: number }>;
+	totalEdits: number;
+}
+
+/** Complete insight analysis result for a completed session. */
+export interface InsightAnalysis {
+	insights: SessionInsight[];
+	toolProfile: ToolProfile;
+	fileProfile: FileProfile;
+}