headlesscode 1.0.2

package/src/memory/uwuchat.ts

@@ -0,0 +1,157 @@
+/**
+ * UwUChatMemoryStore — the harness-side client for the future AIRunner/UwUChat
+ * memory API (Phase 3). See docs/memory-uwuchat-contract.md for the full
+ * endpoint contract + the data-isolation guarantee.
+ *
+ * STATUS: awaiting the AIRunner endpoints. Until a base URL + token are
+ * provided, every method throws a typed `UwUChatMemoryError` with the message
+ * "not implemented — awaiting AIRunner endpoint". Once `UWUCHAT_BASE_URL` (and
+ * optionally `UWUCHAT_TOKEN`) are set, the store fetches the documented
+ * endpoints with native `fetch` and Bearer-token auth.
+ *
+ * It implements the SAME `MemoryStore` interface as `LocalMemoryStore`, so the
+ * harness can swap backends without changing any caller.
+ */
+
+import type { Embedder, FactInput, MemoryFact, MemoryStore, RecallResult, SessionSummary } from "./types.js"
+
+export interface UwUChatMemoryOptions {
+	/** AIRunner/UwUChat base URL. Default: $UWUCHAT_BASE_URL. */
+	baseUrl?: string
+	/** Scoped service token. Default: $UWUCHAT_TOKEN. */
+	token?: string
+	/** Injectable fetch (tests use a fake; default: global fetch). */
+	fetchImpl?: typeof fetch
+	/** Unused here (embeddings are computed harness-side per the spec). */
+	embedder?: Embedder
+}
+
+/** Typed error for UwUChat API failures. */
+export class UwUChatMemoryError extends Error {
+	constructor(
+		message: string,
+		readonly status?: number,
+		readonly body?: unknown,
+	) {
+		super(message)
+		this.name = "UwUChatMemoryError"
+	}
+}
+
+/** Base path prefix for all harness memory endpoints on the AIRunner side. */
+export const API_PREFIX = "/api/v1/harness/memory"
+
+export class UwUChatMemoryStore implements MemoryStore {
+	readonly baseUrl: string
+	private readonly token: string | undefined
+	private readonly fetchImpl: typeof fetch
+
+	constructor(options: UwUChatMemoryOptions = {}) {
+		this.baseUrl = (options.baseUrl ?? process.env.UWUCHAT_BASE_URL ?? "").replace(/\/+$/, "")
+		this.token = options.token ?? process.env.UWUCHAT_TOKEN
+		this.fetchImpl = options.fetchImpl ?? ((input, init) => fetch(input, init))
+	}
+
+	/** Build the absolute URL for an API path under the memory prefix. */
+	endpoint(apiPath: string): string {
+		return `${this.baseUrl}${apiPath}`
+	}
+
+	/** Auth + content headers (Bearer token when configured). */
+	authHeaders(): Record<string, string> {
+		const headers: Record<string, string> = { "Content-Type": "application/json" }
+		if (this.token) {
+			headers["Authorization"] = `Bearer ${this.token}`
+		}
+		return headers
+	}
+
+	private ensureConfigured(): void {
+		if (!this.baseUrl) {
+			throw new UwUChatMemoryError(
+				"UwUChatMemoryStore: not implemented — awaiting AIRunner endpoint (set UWUCHAT_BASE_URL and, if required, UWUCHAT_TOKEN)",
+			)
+		}
+	}
+
+	private async request<T>(method: string, apiPath: string, body?: unknown): Promise<T> {
+		this.ensureConfigured()
+		const init: RequestInit = { method, headers: this.authHeaders() }
+		if (body !== undefined) {
+			init.body = JSON.stringify(body)
+		}
+
+		let response: Response
+		try {
+			response = await this.fetchImpl(this.endpoint(apiPath), init)
+		} catch (error) {
+			throw new UwUChatMemoryError(
+				`UwUChat ${method} ${apiPath} request failed: ${error instanceof Error ? error.message : String(error)}`,
+			)
+		}
+
+		if (!response.ok) {
+			let bodyText = ""
+			try {
+				bodyText = await response.text()
+			} catch {
+				// ignore body read errors
+			}
+			throw new UwUChatMemoryError(
+				`UwUChat ${method} ${apiPath} failed with status ${response.status}`,
+				response.status,
+				bodyText,
+			)
+		}
+
+		try {
+			return (await response.json()) as T
+		} catch (error) {
+			throw new UwUChatMemoryError(`UwUChat ${method} ${apiPath} returned invalid JSON`, response.status)
+		}
+	}
+
+	// ─── MemoryStore implementation (project-scoped) ─────────────────────────
+
+	async listFacts(project: string): Promise<MemoryFact[]> {
+		const data = await this.request<{ facts?: MemoryFact[] }>(
+			"GET",
+			`${API_PREFIX}/facts?project=${encodeURIComponent(project)}`,
+		)
+		return data.facts ?? []
+	}
+
+	async addFact(project: string, factInput: FactInput): Promise<MemoryFact> {
+		const data = await this.request<{ fact: MemoryFact }>("POST", `${API_PREFIX}/record-fact`, {
+			project,
+			fact: factInput,
+		})
+		return data.fact
+	}
+
+	async queryRecall(project: string, query: string, limit = 5): Promise<RecallResult> {
+		const data = await this.request<RecallResult>("POST", `${API_PREFIX}/query-recall`, { project, query, limit })
+		return { facts: data.facts ?? [], summaries: data.summaries ?? [] }
+	}
+
+	async recordSession(project: string, summary: SessionSummary): Promise<void> {
+		await this.request<{ ok?: boolean }>("POST", `${API_PREFIX}/record-session`, { project, session: summary })
+	}
+
+	async listSessions(project: string): Promise<SessionSummary[]> {
+		const data = await this.request<{ sessions?: SessionSummary[] }>(
+			"GET",
+			`${API_PREFIX}/sessions?project=${encodeURIComponent(project)}`,
+		)
+		return data.sessions ?? []
+	}
+
+	async summarize(project: string, options: { maxEntries?: number } = {}): Promise<string> {
+		const query = new URLSearchParams({ project })
+		if (options.maxEntries !== undefined) {
+			query.set("maxEntries", String(options.maxEntries))
+		}
+		const data = await this.request<{ summary: string }>("GET", `${API_PREFIX}/summaries?${query.toString()}`)
+		return data.summary
+	}
+}

package/src/migrate/cli.ts

@@ -0,0 +1,115 @@
+/**
+ * `headlesscode migrate` subcommand — the explicit, human-triggerable version
+ * of the one-time migrations the central store performs automatically on first
+ * use (see src/project-store.ts). Running it is always safe (idempotent): each
+ * migration is skipped when the source is absent or the target already exists,
+ * and every move verifies the content landed before the source is removed.
+ *
+ *   headlesscode migrate [--workspace <path>]
+ *
+ * Migrates:
+ *   1. Global shared instructions out of `~/.roo/` (Zoo-Code-branded) into
+ *      `~/.local/share/headlesscode/shared/` (modes.yaml + rules(-<mode>)/).
+ *   2. The checkpoint store from `~/.headlesscode/checkpoints` into
+ *      `~/.local/share/headlesscode/checkpoints` (a MOVE — real, potentially
+ *      large data is never copied-and-orphaned).
+ *   3. When `--workspace <path>` is given (default: the current directory),
+ *      that workspace's legacy `<root>/.headlesscode/{codesearch,
+ *      mode-models.json, permissions.json}` into the central project store —
+ *      keyed by the repo's git-common-dir, so worktrees share it.
+ */
+
+import * as path from "node:path"
+
+import {
+	isStoreOverridden,
+	migrateCheckpointStore,
+	migrateLegacyProjectData,
+	migrateSharedInstructions,
+	resolveProjectDataDir,
+	resolveProjectIdentity,
+} from "../project-store.js"
+
+const MIGRATE_USAGE = `headlesscode migrate — move legacy headlesscode data into the central store
+
+Usage:
+  headlesscode migrate [--workspace <path>]
+
+The central store is ~/.local/share/headlesscode/ (see src/project-store.ts).
+Migrations are one-time and idempotent; each move is verified before the
+source is removed, so re-running is always safe.
+
+Steps:
+  1. ~/.roo/ -> ~/.local/share/headlesscode/shared/   (global modes + rules)
+  2. ~/.headlesscode/checkpoints -> ~/.local/share/headlesscode/checkpoints
+  3. <workspace>/.headlesscode/{codesearch,mode-models.json,permissions.json}
+     -> ~/.local/share/headlesscode/projects/<key>/ (when --workspace given)
+
+Options:
+  --workspace <path>  Workspace whose legacy .headlesscode/ content to migrate
+                      (default: the current directory)
+  --help              Show this help and exit
+`
+
+export function parseMigrateArgs(argv: string[]): { workspace?: string; help: boolean; error?: string } {
+	const options: { workspace?: string; help: boolean } = { help: false }
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i]
+		switch (arg) {
+			case "--help":
+			case "-h":
+				options.help = true
+				break
+			case "--workspace": {
+				const v = argv[i + 1]
+				if (v === undefined || v.startsWith("--")) {
+					return { ...options, error: "Missing value for --workspace" }
+				}
+				options.workspace = v
+				i++
+				break
+			}
+			default:
+				return { ...options, error: `Unknown argument: ${arg}` }
+		}
+	}
+	return options
+}
+
+export async function migrateMain(argv: string[]): Promise<number> {
+	const { workspace, help, error } = parseMigrateArgs(argv)
+	if (error) {
+		process.stderr.write(`headlesscode migrate: ${error}\n\n${MIGRATE_USAGE}`)
+		return 2
+	}
+	if (help) {
+		process.stdout.write(MIGRATE_USAGE)
+		return 0
+	}
+
+	// Step 1 + 2: global shared instructions + checkpoint store. Log to stdout
+	// (this is the explicit command's report channel). Under a
+	// $HEADLESSCODE_DATA_DIR override (tests/scratch) these two REAL-home-data
+	// migrations are skipped — the override means "don't touch real home data";
+	// the workspace migration below still runs against the override store.
+	const log = (msg: string): void => {
+		process.stdout.write(`[migrate] ${msg}\n`)
+	}
+	if (isStoreOverridden()) {
+		log("skipping global migrations (shared instructions + checkpoints) under a HEADLESSCODE_DATA_DIR override")
+	} else {
+		migrateSharedInstructions({ log })
+		migrateCheckpointStore({ log })
+	}
+
+	// Step 3: the workspace's legacy .headlesscode/ content.
+	const ws = path.resolve(workspace ?? process.cwd())
+	const { keySource } = resolveProjectIdentity(ws)
+	const centralDir = resolveProjectDataDir(ws)
+	migrateLegacyProjectData(ws, keySource, centralDir, { log })
+
+	process.stdout.write(
+		"[migrate] done. New central store root: ~/.local/share/headlesscode/ (per-project data under projects/, checkpoints under checkpoints/, shared instructions under shared/).\n",
+	)
+	return 0
+}

package/src/orchestrator/analyze-cli.ts

@@ -0,0 +1,104 @@
+/**
+ * `headlesscode analyze-worktree` subcommand — ad-hoc, standalone entry
+ * point for src/orchestrator/log-analysis.ts. The orchestrator already
+ * runs this automatically once each group reaches "done" (see cli.ts's
+ * onGroupUpdate); this subcommand exists for pointing it at ANY worktree
+ * by hand — a stalled group mid-round, a worktree from a round that
+ * predates this feature, or just re-reading a report without waiting for
+ * the next orchestrate poll.
+ *
+ *   headlesscode analyze-worktree --worktree <path> [--json]
+ *                                 [--stall-minutes <n>] [--repeat-threshold <n>]
+ */
+
+import { analyzeWorktreeSessions, formatAnalysisReport } from "./log-analysis.js"
+
+const ANALYZE_USAGE = `headlesscode analyze-worktree — deterministic session log analysis
+
+Usage:
+  headlesscode analyze-worktree --worktree <path> [options]
+
+Options:
+  --worktree <path>        Worktree root to analyze (required) — the dir
+                            containing .headlesscode/events/*.jsonl
+  --json                   Print the raw SessionLogAnalysis as JSON instead
+                            of the human-readable report
+  --stall-minutes <n>      Gap between events considered a stall (default 15)
+  --repeat-threshold <n>   Min verbatim repeats to flag a command (default 3)
+  --help                   Show this help and exit
+`
+
+interface AnalyzeCliOptions {
+	worktree: string
+	json: boolean
+	stallMinutes?: number
+	repeatThreshold?: number
+}
+
+export function parseAnalyzeArgs(argv: string[]): AnalyzeCliOptions | { help: true } | { error: string } {
+	let worktree: string | undefined
+	let json = false
+	let stallMinutes: number | undefined
+	let repeatThreshold: number | undefined
+
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i]
+		if (arg === "--help" || arg === "-h") {
+			return { help: true }
+		} else if (arg === "--worktree") {
+			worktree = argv[++i]
+		} else if (arg === "--json") {
+			json = true
+		} else if (arg === "--stall-minutes") {
+			const raw = argv[++i]
+			const n = Number(raw)
+			if (!raw || Number.isNaN(n) || n <= 0) {
+				return { error: `--stall-minutes must be a positive number, got: ${raw}` }
+			}
+			stallMinutes = n
+		} else if (arg === "--repeat-threshold") {
+			const raw = argv[++i]
+			const n = Number(raw)
+			if (!raw || Number.isNaN(n) || n <= 0) {
+				return { error: `--repeat-threshold must be a positive number, got: ${raw}` }
+			}
+			repeatThreshold = n
+		} else {
+			return { error: `unknown argument: ${arg}` }
+		}
+	}
+
+	if (!worktree) {
+		return { error: "--worktree is required" }
+	}
+	return { worktree, json, stallMinutes, repeatThreshold }
+}
+
+export async function analyzeCliMain(argv: string[]): Promise<number> {
+	const parsed = parseAnalyzeArgs(argv)
+	if ("help" in parsed) {
+		process.stdout.write(ANALYZE_USAGE)
+		return 0
+	}
+	if ("error" in parsed) {
+		process.stderr.write(`analyze-worktree: ${parsed.error}\n\n${ANALYZE_USAGE}`)
+		return 2
+	}
+
+	const analysis = await analyzeWorktreeSessions(parsed.worktree, {
+		stallThresholdMs: parsed.stallMinutes !== undefined ? parsed.stallMinutes * 60 * 1000 : undefined,
+		repeatThreshold: parsed.repeatThreshold,
+	})
+
+	if (!analysis) {
+		process.stderr.write(`analyze-worktree: no .headlesscode/events feed found under ${parsed.worktree}\n`)
+		return 1
+	}
+
+	if (parsed.json) {
+		process.stdout.write(JSON.stringify(analysis, null, 2) + "\n")
+	} else {
+		process.stdout.write(formatAnalysisReport(analysis) + "\n")
+	}
+	return 0
+}

package/src/orchestrator/auto-split.ts

@@ -0,0 +1,206 @@
+/**
+ * Auto-split for oversized issues (issue #53's follow-up): the pre-flight
+ * heuristic in split.ts (topLevelSectionCount) was warn-only by design
+ * because a crude "count top-level bullets" signal false-positives on issues
+ * that are genuinely ONE coherent piece of work with many sequential steps —
+ * exploding every bullet into its own issue would be actively worse than
+ * dispatching the oversized issue as-is (it fragments one fix's sequential
+ * steps across unrelated issues that make no sense in isolation).
+ *
+ * This module replaces "warn and let a human decide" with a SEMANTIC split:
+ * an LLM reads the flagged issue and proposes the smallest number of
+ * independently-shippable, coherent sub-issues that partition the work (for
+ * a two-part bug report like "server query is unbounded AND client loading
+ * state is misleading", that's 2 sub-issues, not one per bullet). Fails
+ * OPEN: any failure (LLM error, unparseable response, model proposes fewer
+ * than 2 pieces meaning "this doesn't actually decompose") leaves the
+ * original issue untouched and dispatches it as-is — the same behavior as
+ * before this module existed. A bad split must never be worse than no split.
+ */
+
+import type { LlmClient } from "../engine/types.js"
+import type { IssueSizeWarning, SplitIssue } from "./split.js"
+
+/** One sub-issue the model proposed as an independently-shippable slice of the original. */
+export interface ProposedSubIssue {
+	title: string
+	body: string
+}
+
+/** Never propose fewer than this many pieces — 1 means "don't split", handled as a no-op by the caller. */
+const MIN_SUBISSUES = 2
+
+/** Never propose more than this many — a runaway response must not file dozens of issues from one call. */
+const MAX_SUBISSUES = 8
+
+const SPLIT_SYSTEM_PROMPT =
+	"You split an oversized GitHub issue into a SMALL number of independently-shippable sub-issues. " +
+	"HARD RULES:\n" +
+	"1. Group by INDEPENDENT DELIVERABLE, not by bullet point. If the issue describes N sequential steps of " +
+	"ONE fix (e.g. 'step 1: add an index, step 2: change the query, step 3: verify'), those steps belong in " +
+	"ONE sub-issue together — splitting sequential steps of a single fix across issues is WRONG.\n" +
+	"2. Only split along boundaries where the pieces could genuinely ship, be reviewed, and be tested " +
+	"independently (e.g. a server-side fix vs. a client-side fix for the same bug are usually independent; " +
+	"the individual code changes inside ONE of those fixes usually are not).\n" +
+	"3. If the issue is really just one coherent piece of work with a long list of steps/details — NOT " +
+	`multiple independent deliverables — return a JSON array with FEWER THAN ${MIN_SUBISSUES} elements ` +
+	"(e.g. an empty array) to say so. Do not force a split that doesn't exist.\n" +
+	"4. Each sub-issue's body must be self-contained: include everything from the original body relevant to " +
+	"that piece (file paths, line numbers, root-cause analysis, verification steps) so implementing it doesn't " +
+	"require re-reading the original issue. Do not invent details the original didn't contain.\n" +
+	"5. Output ONLY a JSON array of objects with exactly two string fields, \"title\" and \"body\" — no " +
+	"markdown fences, no preamble, no commentary."
+
+function buildSplitUserPrompt(issue: SplitIssue): string {
+	return (
+		`Issue #${issue.number}: ${issue.title}\n\n` +
+		`=== BODY BEGIN ===\n${issue.body ?? "(no body)"}\n=== BODY END ===`
+	)
+}
+
+/** Extract a JSON array from a model response that may still wrap it in prose or a code fence, despite rule 5. */
+function extractJsonArray(text: string): unknown {
+	const trimmed = text.trim()
+	try {
+		return JSON.parse(trimmed)
+	} catch {
+		// Fall back to the first [...] span — tolerates an accidental ```json fence or a stray leading sentence.
+		const match = trimmed.match(/\[[\s\S]*\]/)
+		if (!match) {
+			throw new Error("no JSON array found in split proposal response")
+		}
+		return JSON.parse(match[0])
+	}
+}
+
+/**
+ * Ask the model to propose a semantic split for one oversized issue. Returns
+ * an empty array (not an error) when the model determines the issue is
+ * genuinely one coherent piece of work — that is a valid, expected outcome,
+ * not a failure. Throws only on a real failure (LLM error, garbage response)
+ * so the caller can distinguish "model said don't split" from "couldn't ask."
+ */
+export async function proposeSemanticSplit(
+	issue: SplitIssue,
+	llmClient: LlmClient,
+	model: string,
+): Promise<ProposedSubIssue[]> {
+	const response = await llmClient.createChatCompletion({
+		model,
+		messages: [
+			{ role: "system", content: SPLIT_SYSTEM_PROMPT },
+			{ role: "user", content: buildSplitUserPrompt(issue) },
+		],
+	})
+	const text = response.message.content
+	if (typeof text !== "string" || text.trim() === "") {
+		throw new Error("split proposal returned an empty message")
+	}
+	const parsed = extractJsonArray(text)
+	if (!Array.isArray(parsed)) {
+		throw new Error("split proposal response was not a JSON array")
+	}
+	const proposals: ProposedSubIssue[] = []
+	for (const entry of parsed) {
+		if (
+			entry &&
+			typeof entry === "object" &&
+			typeof (entry as { title?: unknown }).title === "string" &&
+			typeof (entry as { body?: unknown }).body === "string"
+		) {
+			proposals.push({ title: (entry as { title: string }).title, body: (entry as { body: string }).body })
+		}
+	}
+	if (proposals.length < MIN_SUBISSUES) {
+		return [] // model said (or effectively said, via malformed entries): don't split.
+	}
+	return proposals.slice(0, MAX_SUBISSUES)
+}
+
+/** One flagged issue's outcome, for a human-readable dispatch-time report. */
+export interface AutoSplitOutcome {
+	number: number
+	title: string
+	outcome: "split" | "kept-as-is" | "failed"
+	/** Present when outcome is "split": the newly filed sub-issues. */
+	created?: Array<{ number: number; title: string; url: string }>
+	/** Present when outcome is "failed": why the split attempt didn't happen. */
+	reason?: string
+}
+
+/**
+ * For every issue flagged by the pre-flight size check, attempt a semantic
+ * split and file the result as real GitHub issues, replacing the oversized
+ * issue in the returned list. Fails open per-issue: any single issue's
+ * failure (LLM error, filing error) falls back to keeping that issue
+ * unchanged and dispatching it as-is — one bad split must never abort the
+ * whole round or leave OTHER issues un-split.
+ *
+ * `proposeSplit`/`createIssue`/`closeParent` are injected (not hardcoded to
+ * OpenRouter/gh) so this is unit-testable without network access — the real
+ * orchestrate command wires them to proposeSemanticSplit/createGhIssue/a
+ * `gh issue close --comment` call.
+ */
+export async function autoSplitOversizedIssues(
+	issues: SplitIssue[],
+	warnings: IssueSizeWarning[],
+	deps: {
+		proposeSplit: (issue: SplitIssue) => Promise<ProposedSubIssue[]>
+		createIssue: (issue: SplitIssue) => { number: number; url: string }
+		closeParent: (issueNumber: number, comment: string) => void
+	},
+): Promise<{ issues: SplitIssue[]; outcomes: AutoSplitOutcome[] }> {
+	const flagged = new Set(warnings.map((w) => w.number))
+	const outcomes: AutoSplitOutcome[] = []
+	const next: SplitIssue[] = []
+
+	for (const issue of issues) {
+		if (!flagged.has(issue.number)) {
+			next.push(issue)
+			continue
+		}
+		let proposals: ProposedSubIssue[]
+		try {
+			proposals = await deps.proposeSplit(issue)
+		} catch (err) {
+			outcomes.push({
+				number: issue.number,
+				title: issue.title,
+				outcome: "failed",
+				reason: err instanceof Error ? err.message : String(err),
+			})
+			next.push(issue)
+			continue
+		}
+		if (proposals.length < MIN_SUBISSUES) {
+			outcomes.push({ number: issue.number, title: issue.title, outcome: "kept-as-is" })
+			next.push(issue)
+			continue
+		}
+		try {
+			const created: Array<{ number: number; title: string; url: string }> = []
+			for (const p of proposals) {
+				const real = deps.createIssue({ number: -1, title: p.title, body: `${p.body}\n\n---\nSplit from #${issue.number}.` })
+				created.push({ number: real.number, title: p.title, url: real.url })
+				next.push({ number: real.number, title: p.title, body: p.body })
+			}
+			deps.closeParent(
+				issue.number,
+				`Auto-split into ${created.length} sub-issue(s) by headlesscode's pre-flight size check (issue #53) — ` +
+					`the body read like independent pieces of work, so each is dispatched separately instead of risking an ` +
+					`iteration-cap/budget burn on one worker:\n\n` +
+					created.map((c) => `- #${c.number}: ${c.title}`).join("\n"),
+			)
+			outcomes.push({ number: issue.number, title: issue.title, outcome: "split", created })
+		} catch (err) {
+			outcomes.push({
+				number: issue.number,
+				title: issue.title,
+				outcome: "failed",
+				reason: err instanceof Error ? err.message : String(err),
+			})
+			next.push(issue)
+		}
+	}
+	return { issues: next, outcomes }
+}