headlesscode 1.0.2

package/src/orchestrator/git-sync.ts

@@ -0,0 +1,250 @@
+/**
+ * Local-branch ↔ origin reconciliation for the orchestration workflow
+ * (issue #25).
+ *
+ * The failure mode this exists to prevent: local `master` silently
+ * accumulates commits for an entire session without ever being pushed.
+ * Parallel worktrees branch off local `master` / `origin/master` while GitHub
+ * PR merges only ever move `origin/master`, so the two diverge and every
+ * PR-merge cycle pays for it with re-merge conflict cascades (three separate
+ * re-merge-and-retest cycles in one session, zero functional benefit).
+ *
+ * Natural checkpoints call `syncBranchWithOrigin`:
+ *   - `orchestrate` before spawning, so a round's branches start from what's
+ *     actually on GitHub;
+ *   - `orchestrate cleanup --apply` after a round settles.
+ *
+ * Both are best-effort auxiliary steps matching the repo's non-fatal failure
+ * pattern: a failure (auth, divergence, offline) is collected as a warning
+ * for the caller to print loudly — it never aborts the round or fails
+ * cleanup. Setting `HEADLESSCODE_ORCHESTRATE_NO_SYNC=1` disables the mutation
+ * entirely; only a read-only drift report (with a loud warning past
+ * `TRIVIAL_DRIFT_AHEAD`) is produced.
+ */
+
+import { execFileSync } from "node:child_process"
+
+/** Read-only drift report: how far local <branch> is from origin/<branch>. */
+export interface BranchSyncStatus {
+	branch: string
+	remoteRef: string
+	/** Commits on <branch> that origin/<branch> does not have. */
+	ahead: number
+	/** Commits on origin/<branch> that <branch> does not have. */
+	behind: number
+}
+
+/** Outcome of one sync attempt; never throws — everything is a note/warning. */
+export interface BranchSyncResult {
+	branch: string
+	remoteRef: string
+	ahead: number
+	behind: number
+	/** Sync was skipped entirely (no origin remote, detached HEAD, never pushed). */
+	skipped: boolean
+	skipReason?: string
+	fetched: boolean
+	pushed: boolean
+	fastForwarded: boolean
+	notes: string[]
+	warnings: string[]
+}
+
+/** Unpushed drift above this count is "more than a trivial amount" — the
+ *  read-only (`HEADLESSCODE_ORCHESTRATE_NO_SYNC`) path warns only past it. */
+export const TRIVIAL_DRIFT_AHEAD = 5
+
+/** Setting this env var disables the automatic sync (read-only drift report). */
+export const ORCHESTRATE_SYNC_DISABLED_ENV = "HEADLESSCODE_ORCHESTRATE_NO_SYNC"
+
+function git(repo: string, args: string[], timeoutMs: number): string {
+	return execFileSync("git", ["-C", repo, ...args], {
+		encoding: "utf-8",
+		stdio: ["ignore", "pipe", "ignore"],
+		timeout: timeoutMs,
+	}).trim()
+}
+
+/** The repo's checked-out branch ("master"/"main"), or undefined when detached. */
+function resolveHeadBranch(repo: string): string | undefined {
+	try {
+		const branch = git(repo, ["symbolic-ref", "--short", "HEAD"], 5000)
+		return branch === "" ? undefined : branch
+	} catch {
+		return undefined
+	}
+}
+
+function hasRemoteOrigin(repo: string): boolean {
+	try {
+		return git(repo, ["remote"], 5000).split("\n").includes("origin")
+	} catch {
+		return false
+	}
+}
+
+function remoteRefExists(repo: string, remoteRef: string): boolean {
+	try {
+		execFileSync("git", ["-C", repo, "rev-parse", "--verify", "--quiet", remoteRef], { stdio: "ignore", timeout: 5000 })
+		return true
+	} catch {
+		return false
+	}
+}
+
+function countAheadBehind(repo: string, remoteRef: string, branch: string): { ahead: number; behind: number } {
+	const count = (args: string[]): number => {
+		try {
+			return Number(git(repo, args, 10_000)) || 0
+		} catch {
+			return 0
+		}
+	}
+	return {
+		ahead: count(["rev-list", "--count", `${remoteRef}..${branch}`]),
+		behind: count(["rev-list", "--count", `${branch}..${remoteRef}`]),
+	}
+}
+
+function errMessage(err: unknown): string {
+	return err instanceof Error ? err.message : String(err)
+}
+
+/**
+ * Read-only drift report against the CURRENT (possibly stale) origin ref —
+ * no fetch, no mutation. `undefined` when there is nothing to compare
+ * against (detached HEAD, no origin remote, branch never pushed).
+ */
+export function branchSyncStatus(repo: string, branch?: string): BranchSyncStatus | undefined {
+	const head = resolveHeadBranch(repo)
+	const target = branch ?? head
+	if (!target || !hasRemoteOrigin(repo)) {
+		return undefined
+	}
+	const remoteRef = `origin/${target}`
+	if (!remoteRefExists(repo, remoteRef)) {
+		return undefined
+	}
+	const { ahead, behind } = countAheadBehind(repo, remoteRef, target)
+	return { branch: target, remoteRef, ahead, behind }
+}
+
+/**
+ * Fetch origin, push local-only commits, then fast-forward local onto origin
+ * (only when local is strictly behind and it is the checked-out branch). A
+ * divergence (local ahead AND behind) cannot be auto-reconciled — it is
+ * reported as a loud warning. Never throws.
+ */
+export function syncBranchWithOrigin(repo: string, branch?: string): BranchSyncResult {
+	const head = resolveHeadBranch(repo)
+	const target = branch ?? head
+	if (!target) {
+		return {
+			branch: "", remoteRef: "", ahead: 0, behind: 0,
+			skipped: true, skipReason: "detached HEAD — cannot determine the branch to sync",
+			fetched: false, pushed: false, fastForwarded: false, notes: [], warnings: [],
+		}
+	}
+	const remoteRef = `origin/${target}`
+	if (!hasRemoteOrigin(repo)) {
+		return {
+			branch: target, remoteRef, ahead: 0, behind: 0,
+			skipped: true, skipReason: `no git remote named 'origin' — nothing to sync`,
+			fetched: false, pushed: false, fastForwarded: false, notes: [], warnings: [],
+		}
+	}
+	if (!remoteRefExists(repo, remoteRef)) {
+		return {
+			branch: target, remoteRef, ahead: 0, behind: 0,
+			skipped: true, skipReason: `${remoteRef} does not exist — this branch was never pushed`,
+			fetched: false, pushed: false, fastForwarded: false, notes: [], warnings: [],
+		}
+	}
+
+	const notes: string[] = []
+	const warnings: string[] = []
+
+	let fetched = false
+	try {
+		git(repo, ["fetch", "origin", target], 60_000)
+		fetched = true
+	} catch (err) {
+		return {
+			branch: target, remoteRef, ahead: 0, behind: 0, skipped: false,
+			fetched: false, pushed: false, fastForwarded: false, notes: [],
+			warnings: [`git fetch origin ${target} failed: ${errMessage(err)} — cannot sync local ${target} with ${remoteRef}`],
+		}
+	}
+
+	let { ahead, behind } = countAheadBehind(repo, remoteRef, target)
+	let pushed = false
+	let fastForwarded = false
+
+	if (ahead > 0) {
+		try {
+			git(repo, ["push", "origin", target], 60_000)
+			pushed = true
+			notes.push(`pushed ${ahead} commit(s) to ${remoteRef}`)
+			ahead = 0
+		} catch (err) {
+			warnings.push(`could not push ${ahead} commit(s) to ${remoteRef}: ${errMessage(err)}`)
+		}
+	}
+
+	if (behind > 0) {
+		if (target !== head) {
+			notes.push(`local ${target} is ${behind} commit(s) behind ${remoteRef} — not fast-forwarding (only the checked-out branch is auto-merged)`)
+		} else {
+			try {
+				git(repo, ["merge", "--ff-only", remoteRef], 30_000)
+				fastForwarded = true
+				notes.push(`fast-forwarded ${target} onto ${remoteRef} (${behind} commit(s))`)
+				behind = 0
+			} catch (err) {
+				warnings.push(`could not fast-forward ${target} onto ${remoteRef}: ${errMessage(err)}`)
+			}
+		}
+	}
+
+	return { branch: target, remoteRef, ahead, behind, skipped: false, fetched, pushed, fastForwarded, notes, warnings }
+}
+
+/** Informational lines describing what the sync did (empty for a silent no-op). */
+export function syncSummaryLines(result: BranchSyncResult): string[] {
+	if (result.skipped) {
+		return []
+	}
+	if (result.pushed || result.fastForwarded) {
+		const bits: string[] = []
+		if (result.pushed) {
+			bits.push("pushed local commits")
+		}
+		if (result.fastForwarded) {
+			bits.push("fast-forwarded onto origin")
+		}
+		return [`${result.branch} synced with ${result.remoteRef} (${bits.join(", ")})`]
+	}
+	if (result.ahead > 0 || result.behind > 0) {
+		return [`${result.branch} NOT fully synced with ${result.remoteRef} (${result.ahead} ahead, ${result.behind} behind)`]
+	}
+	if (result.warnings.length === 0) {
+		return [`${result.branch} is in sync with ${result.remoteRef}`]
+	}
+	return []
+}
+
+/** Loud, actionable warning lines for drift the sync could not fix. */
+export function syncWarningLines(result: BranchSyncResult, repo: string): string[] {
+	if (result.skipped) {
+		return []
+	}
+	const lines = [...result.warnings]
+	if (result.ahead > 0 || result.behind > 0) {
+		lines.push(
+			`WARNING: local ${result.branch} is ${result.ahead} commit(s) ahead and ${result.behind} behind ${result.remoteRef} ` +
+				`after the sync attempt — unpushed drift like this causes merge-conflict cascades at PR-merge time (issue #25). ` +
+				`Reconcile manually: git -C ${repo} fetch origin && git -C ${repo} merge --ff-only origin/${result.branch} && git -C ${repo} push origin ${result.branch}`,
+		)
+	}
+	return lines
+}

package/src/orchestrator/index.ts

@@ -0,0 +1,153 @@
+/**
+ * Phase 2 orchestration layer — public exports.
+ *
+ * Replaces a GUI orchestration flow (xdotool inject + wmctrl wake-up) with
+ * headless harness subprocesses, reusing the issue-splitting heuristics and
+ * the reviewer checklist.
+ */
+
+export {
+	ISSUE_SIZE_WARN_THRESHOLD,
+	issueShape,
+	issueSizeWarnings,
+	shapeOf,
+	splitIssues,
+	topLevelSectionCount,
+} from "./split.js"
+export type { IssueSizeWarning, SplitIssue, WorktreeSpec } from "./split.js"
+
+export { loadState, loadStateSync, saveState, saveStateSync, updateGroup, defaultState } from "./state.js"
+export type { OrchestratorGroup, OrchestratorState } from "./state.js"
+
+export {
+	runReview,
+	runReviewWithRetries,
+	parseReviewResult,
+	reviewTools,
+	HARNESS_ROOT,
+	DEFAULT_REVIEW_PROMPT_PATH,
+} from "./reviewer.js"
+export type { ReviewOptions, ReviewResult } from "./reviewer.js"
+
+export { analyzeWorktreeSessions, formatAnalysisReport, listSessionIds } from "./log-analysis.js"
+export type { SessionLogAnalysis, AnalyzeOptions, ToolErrorSample, StallGap, RepeatedCommand } from "./log-analysis.js"
+
+export { analyzeCliMain, parseAnalyzeArgs } from "./analyze-cli.js"
+
+export {
+	costHistoryFilePath,
+	appendCostHistoryRecord,
+	readCostHistory,
+	recordGroupCost,
+	sessionCostHistoryFilePath,
+	appendSessionCostRecord,
+	readSessionCostHistory,
+	recordAllSessionCosts,
+} from "./cost-history.js"
+export type { CostHistoryRecord, SessionCostRecord } from "./cost-history.js"
+
+export { costHistoryCliMain, parseCostHistoryArgs } from "./cost-history-cli.js"
+
+export {
+	aggregateByShape,
+	buildEstimateSection,
+	estimateGroup,
+	estimateGroups,
+	estimateIssue,
+	MIN_SHAPE_SAMPLES,
+} from "./cost-estimate.js"
+export type { GroupEstimate, IssueEstimate, ShapeStats } from "./cost-estimate.js"
+
+
+export { watchGroups, inspectGroup, tailLog, groupWorktreePath, isPidAlive, DEFAULT_POLL_INTERVAL_MS, DEFAULT_STALL_TIMEOUT_MS } from "./watch.js"
+export type { WatchOptions, WatchSummary } from "./watch.js"
+
+export { checkMergedByAncestor, checkMergedByGitHubPr } from "./merge-check.js"
+export type { MergeCheckResult } from "./merge-check.js"
+
+export {
+	applyCleanup,
+	assessGroupCleanup,
+	assessGroupCleanupSync,
+	checkGroupMerged,
+	cleanupMain,
+	parseCleanupArgs,
+	planCleanup,
+	removeHarnessArtifacts,
+	removeKnownSafeArtifacts,
+	resolveBaseBranch,
+	resolveGroupBranch,
+	worktreeUncommitted,
+} from "./cleanup.js"
+export type { CleanupDeps, CleanupPlan, CleanupPlanEntry, CleanupRunResult, CleanupStatus, GhWiring } from "./cleanup.js"
+
+export {
+	branchSyncStatus,
+	ORCHESTRATE_SYNC_DISABLED_ENV,
+	syncBranchWithOrigin,
+	syncSummaryLines,
+	syncWarningLines,
+	TRIVIAL_DRIFT_AHEAD,
+} from "./git-sync.js"
+export type { BranchSyncResult, BranchSyncStatus } from "./git-sync.js"
+
+export {
+	buildStatusSummary,
+	formatStatusText,
+	reconcileGroups,
+	verdictLine,
+	waitForTerminalState,
+	isTerminalStatus,
+	TERMINAL_STATUSES,
+	DEFAULT_STATUS_POLL_INTERVAL_MS,
+	DEFAULT_STATUS_TIMEOUT_MS,
+} from "./status.js"
+export type {
+	StatusSummary,
+	StatusCounts,
+	StatusGroupRow,
+	WaitForTerminalOptions,
+	WaitForTerminalResult,
+	ReconcileHooks,
+	ReconcileResult,
+} from "./status.js"
+
+// Issue #14: standalone review/rework/resume subcommands (resume.ts).
+export {
+	findingsFromCommentBodies,
+	fetchFindingsFromIssueComments,
+	parseResumeArgs,
+	parseReviewArgs,
+	parseReworkArgs,
+	prHeadBranch,
+	rebuildPatchFromMarkers,
+	recheckoutWorktree,
+	recordSettledCost,
+	resumeGroup,
+	resumeMain,
+	reviewMain,
+	reworkMain,
+	runQaStep,
+	runReviewStep,
+	runReworkStep,
+	resolveTargetGroups,
+} from "./resume.js"
+export type {
+	QaStepOptions,
+	QaStepResult,
+	RecordCostOptions,
+	ResumeCliOptions,
+	ResumeGroupOptions,
+	ResumeGroupResult,
+	ResumeIo,
+	ResumeOutcome,
+	ResumeTarget,
+	ResolveTargetHooks,
+	ReviewCliOptions,
+	ReviewStepOptions,
+	ReviewStepResult,
+	ReworkCliOptions,
+	ReworkOutcome,
+	ReworkStepOptions,
+	ReworkStepResult,
+} from "./resume.js"

package/src/orchestrator/merge-check.ts

@@ -0,0 +1,108 @@
+/**
+ * Deterministic "is this group's work merged?" predicates for `orchestrate
+ * cleanup` (see cleanup.ts). Two sources of truth, dispatched by which
+ * workflow produced the group — never a heuristic:
+ *
+ *   - checkMergedByAncestor: local merge (`git merge <branch>` /
+ *     fast-forward into the base branch). `git merge-base --is-ancestor
+ *     <branchTip> <base>` is provable with total certainty — exit 0 means
+ *     every commit on the branch is in history. No guessing, no network.
+ *   - checkMergedByGitHubPr: GitHub PR merge (squash or rebase). GitHub
+ *     creates a NEW commit whose hash is nothing on the worker's branch, so
+ *     the ancestor check above would wrongly say "not merged" — the only
+ *     correct answer for that workflow is GitHub's server-computed `.merged`
+ *     field (GET /repos/{owner}/{repo}/pulls/{number}).
+ *
+ * Both checks are conservative by construction: an API error or unexpected
+ * git failure is "unknown" (via checkMergedByGitHubPr) or a throw (ancestor
+ * check) — never guessed as merged.
+ */
+
+import { execFileSync } from "node:child_process"
+
+import { getPullRequestStatus, OpenPrError } from "../github/pr.js"
+
+export type MergeCheckResult =
+	| { merged: true; via: "local-ancestor" | "github-pr"; detail: string }
+	| { merged: false; via: "local-ancestor" | "github-pr" | "unknown"; detail: string }
+
+/**
+ * Local-merge check — no network, fully deterministic. Pass the branch names
+ * (or commits) directly; git resolves them itself.
+ *
+ * Exit-code contract (git's documented behavior for
+ * `merge-base --is-ancestor`):
+ *   0  the branch tip IS an ancestor of baseBranch → merged
+ *   1  not an ancestor → not merged
+ *   anything else (e.g. 128 for a missing ref) → THROW; an unknown git
+ *   state must never be guessed as merged or not-merged.
+ */
+export function checkMergedByAncestor(repo: string, branch: string, baseBranch: string): MergeCheckResult {
+	let status: number | null
+	try {
+		execFileSync("git", ["-C", repo, "merge-base", "--is-ancestor", branch, baseBranch], {
+			stdio: "ignore",
+			timeout: 10_000,
+		})
+		status = 0
+	} catch (err) {
+		status = (err as { status?: number }).status ?? null
+	}
+	if (status === 0) {
+		return {
+			merged: true,
+			via: "local-ancestor",
+			detail: `${branch} tip is an ancestor of ${baseBranch}`,
+		}
+	}
+	if (status === 1) {
+		return {
+			merged: false,
+			via: "local-ancestor",
+			detail: `${branch} tip is NOT an ancestor of ${baseBranch}`,
+		}
+	}
+	throw new Error(
+		`git merge-base --is-ancestor ${branch} ${baseBranch} failed (exit ${status ?? "unknown"}) — merge status unknown`,
+	)
+}
+
+/**
+ * GitHub PR check — only attempted when the group records a PR number. Asks
+ * GitHub directly and trusts the server-computed `.merged` boolean (the only
+ * correct answer for squash/rebase merges). An API/network failure fails
+ * CLOSED as `{ merged: false, via: "unknown" }` — an unverifiable merge is
+ * never treated as merged.
+ */
+export async function checkMergedByGitHubPr(options: {
+	owner: string
+	repo: string
+	prNumber: number
+	getInstallationToken: () => Promise<string>
+	/** API base URL override (tests/mocks; default api.github.com). */
+	baseUrl?: string
+	/** Injectable fetch for tests (default: global fetch). */
+	fetchImpl?: typeof fetch
+}): Promise<MergeCheckResult> {
+	const { owner, repo, prNumber } = options
+	try {
+		const status = await getPullRequestStatus({
+			owner,
+			repo,
+			prNumber,
+			getToken: options.getInstallationToken,
+			...(options.baseUrl ? { baseUrl: options.baseUrl } : {}),
+			...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
+		})
+		if (status.merged) {
+			return { merged: true, via: "github-pr", detail: `PR #${prNumber} merged (state ${status.state})` }
+		}
+		return { merged: false, via: "github-pr", detail: `PR #${prNumber} not merged (state ${status.state})` }
+	} catch (err) {
+		const detail =
+			err instanceof OpenPrError
+				? `GitHub API error (GET ${err.url}, HTTP ${err.status}): ${err.message}`
+				: `GitHub PR check error: ${err instanceof Error ? err.message : String(err)}`
+		return { merged: false, via: "unknown", detail }
+	}
+}