@onyx-robotics/agent 0.1.0

package/src/lib/metrics.ts

@@ -0,0 +1,41 @@
+export function parseMetricLines(stdout: string, fallbackName = "score") {
+  const metrics: Record<string, number> = {}
+  for (const line of stdout.split("\n")) {
+    const match = line
+      .trim()
+      .match(/^METRIC\s+([A-Za-z0-9_.:-]+)=(-?\d+(?:\.\d+)?(?:e[+-]?\d+)?)$/i)
+    if (!match) continue
+    metrics[match[1]!] = Number(match[2])
+  }
+
+  if (Object.keys(metrics).length === 0) {
+    const trimmed = stdout.trim()
+    if (/^-?\d+(?:\.\d+)?(?:e[+-]?\d+)?$/i.test(trimmed)) {
+      metrics[fallbackName] = Number(trimmed)
+    }
+  }
+
+  return metrics
+}
+
+export function summarizeOutput(stdout: string, stderr: string) {
+  return [stdout.trim(), stderr.trim()]
+    .filter(Boolean)
+    .join("\n--- stderr ---\n")
+    .slice(0, 4000)
+}
+
+export function primaryMetric(
+  metrics: Record<string, number>,
+  preferredName: string
+): { name: string; value: number | null } {
+  if (Object.hasOwn(metrics, preferredName)) {
+    return { name: preferredName, value: metrics[preferredName] ?? null }
+  }
+
+  const [firstName, firstValue] = Object.entries(metrics)[0] ?? []
+  return {
+    name: firstName ?? preferredName,
+    value: firstValue ?? null,
+  }
+}

package/src/lib/outbox.ts

@@ -0,0 +1,173 @@
+import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises"
+import { randomUUID } from "node:crypto"
+import { join } from "node:path"
+
+import {
+  localResearchRecordSchema,
+  type LocalResearchExperimentLoggedRecord,
+  type LocalResearchRecord,
+} from "../protocol"
+
+import { gitDir } from "./git"
+
+export type CliState = {
+  projectId?: string
+  projectPath?: string
+  branches: Record<
+    string,
+    {
+      branchId?: string
+      projectPath?: string
+      gitBranchName?: string
+      baseCommitSha?: string | null
+      description?: string | null
+      metricName?: string
+      metricUnit?: string | null
+      metricDirection?: "maximize" | "minimize"
+    }
+  >
+}
+
+export type LastRunRecord = Omit<
+  LocalResearchExperimentLoggedRecord,
+  "type" | "schemaVersion" | "createdAt" | "name" | "description"
+> & {
+  schemaVersion: 1
+  createdAt: string
+}
+
+export async function onyxStateDir(root: string) {
+  const dir = join(await gitDir(root), "onyx")
+  await mkdir(dir, { recursive: true })
+  return dir
+}
+
+export async function outboxPath(root: string) {
+  return join(await onyxStateDir(root), "outbox.jsonl")
+}
+
+export async function statePath(root: string) {
+  return join(await onyxStateDir(root), "state.json")
+}
+
+export async function lastRunPath(root: string) {
+  return join(await onyxStateDir(root), "last-run.json")
+}
+
+/** Stable idempotency key persisted with the record and re-sent on every retry. */
+export function clientRunRef(branchName: string) {
+  return `local/${branchName}/${randomUUID()}`
+}
+
+export async function appendOutbox(root: string, record: LocalResearchRecord) {
+  const validated = localResearchRecordSchema.parse(record)
+  await writeFile(await outboxPath(root), `${JSON.stringify(validated)}\n`, {
+    encoding: "utf8",
+    flag: "a",
+  })
+}
+
+/**
+ * Reads queued records. Corrupt or partially-written lines are skipped and
+ * counted rather than thrown, so a crash mid-append never wedges the outbox.
+ */
+export async function readOutbox(
+  root: string
+): Promise<{ records: LocalResearchRecord[]; corrupt: number }> {
+  let text = ""
+  try {
+    text = await readFile(await outboxPath(root), "utf8")
+  } catch {
+    return { records: [], corrupt: 0 }
+  }
+
+  const records: LocalResearchRecord[] = []
+  let corrupt = 0
+
+  for (const line of text.split("\n")) {
+    const trimmed = line.trim()
+    if (!trimmed) continue
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(trimmed)
+    } catch {
+      corrupt += 1
+      continue
+    }
+    const result = localResearchRecordSchema.safeParse(parsed)
+    if (result.success) {
+      records.push(result.data)
+    } else {
+      corrupt += 1
+    }
+  }
+
+  return { records, corrupt }
+}
+
+/** Atomically replaces the outbox with the still-pending records. */
+export async function rewriteOutbox(
+  root: string,
+  records: LocalResearchRecord[]
+) {
+  const path = await outboxPath(root)
+  const body = records.map((record) => JSON.stringify(record)).join("\n")
+  const tmp = `${path}.tmp`
+  await writeFile(tmp, body ? `${body}\n` : "", "utf8")
+  await rename(tmp, path)
+}
+
+export async function readState(root: string): Promise<CliState> {
+  try {
+    const parsed = JSON.parse(
+      await readFile(await statePath(root), "utf8")
+    ) as Partial<CliState>
+    return {
+      projectId: parsed.projectId,
+      projectPath: parsed.projectPath,
+      branches: parsed.branches ?? {},
+    }
+  } catch {
+    return { branches: {} }
+  }
+}
+
+export async function writeState(root: string, state: CliState) {
+  const path = await statePath(root)
+  const tmp = `${path}.tmp`
+  await writeFile(tmp, `${JSON.stringify(state, null, 2)}\n`, "utf8")
+  await rename(tmp, path)
+}
+
+export async function readLastRun(root: string): Promise<LastRunRecord | null> {
+  try {
+    const parsed = JSON.parse(await readFile(await lastRunPath(root), "utf8"))
+    if (
+      parsed &&
+      typeof parsed === "object" &&
+      parsed.schemaVersion === 1 &&
+      typeof parsed.runRef === "string"
+    ) {
+      return parsed as LastRunRecord
+    }
+  } catch {
+    return null
+  }
+
+  return null
+}
+
+export async function writeLastRun(root: string, record: LastRunRecord) {
+  const path = await lastRunPath(root)
+  const tmp = `${path}.tmp`
+  await writeFile(tmp, `${JSON.stringify(record, null, 2)}\n`, "utf8")
+  await rename(tmp, path)
+}
+
+export async function clearLastRun(root: string) {
+  try {
+    await unlink(await lastRunPath(root))
+  } catch {
+    // no last run to clear
+  }
+}

package/src/lib/process.ts

@@ -0,0 +1,73 @@
+import { spawn } from "node:child_process"
+import { stat } from "node:fs/promises"
+
+export type ProcessResult = {
+  code: number | null
+  stdout: string
+  stderr: string
+  timedOut: boolean
+}
+
+export function runProcess(
+  command: string,
+  args: string[],
+  options: { cwd?: string; env?: NodeJS.ProcessEnv; timeoutMs?: number } = {}
+): Promise<ProcessResult> {
+  return new Promise((resolveProcess, reject) => {
+    const child = spawn(command, args, {
+      cwd: options.cwd,
+      env: options.env,
+      stdio: ["ignore", "pipe", "pipe"],
+    })
+    const stdout: Buffer[] = []
+    const stderr: Buffer[] = []
+    let timedOut = false
+    const timeout =
+      options.timeoutMs === undefined
+        ? null
+        : setTimeout(() => {
+            timedOut = true
+            child.kill("SIGTERM")
+          }, options.timeoutMs)
+
+    child.stdout.on("data", (chunk: Buffer) => stdout.push(chunk))
+    child.stderr.on("data", (chunk: Buffer) => stderr.push(chunk))
+    child.on("error", reject)
+    child.on("close", (code) => {
+      if (timeout) clearTimeout(timeout)
+      resolveProcess({
+        code,
+        stdout: Buffer.concat(stdout).toString("utf8"),
+        stderr: Buffer.concat(stderr).toString("utf8"),
+        timedOut,
+      })
+    })
+  })
+}
+
+export async function commandOutput(
+  command: string,
+  args: string[],
+  cwd?: string
+) {
+  const result = await runProcess(command, args, { cwd })
+  if (result.code !== 0 || result.timedOut) {
+    throw new Error(
+      `${command} ${args.join(" ")} failed: ${
+        result.timedOut
+          ? "timed out"
+          : result.stderr.trim() || result.stdout.trim()
+      }`
+    )
+  }
+  return result.stdout.trim()
+}
+
+export async function pathExists(path: string) {
+  try {
+    await stat(path)
+    return true
+  } catch {
+    return false
+  }
+}

package/src/lib/project.ts

@@ -0,0 +1,42 @@
+import { join } from "node:path"
+
+import type { Args } from "./args"
+import { readState } from "./outbox"
+
+export const ONYX_DIR = "onyx"
+
+export function normalizeProjectPath(value?: string | null) {
+  const path = (value ?? "").trim().replace(/^\/+|\/+$/g, "")
+  if (
+    path.includes("\0") ||
+    path.split("/").some((segment) => segment === "..")
+  ) {
+    throw new Error("--project-path must be a relative path without '..'")
+  }
+  return path
+}
+
+export async function resolveProjectPath(root: string, args: Args) {
+  if (args.options["project-path"] !== undefined) {
+    return normalizeProjectPath(args.options["project-path"])
+  }
+
+  const state = await readState(root)
+  return normalizeProjectPath(state.projectPath)
+}
+
+export function scopedRoot(root: string, projectPath: string) {
+  return projectPath ? join(root, projectPath) : root
+}
+
+export function onyxPath(
+  root: string,
+  projectPath: string,
+  ...segments: string[]
+) {
+  return join(scopedRoot(root, projectPath), ONYX_DIR, ...segments)
+}
+
+export function branchStateKey(projectPath: string, branchName: string) {
+  return projectPath ? `${projectPath}:${branchName}` : branchName
+}

package/src/lib/skill-content.ts

@@ -0,0 +1 @@
+export const ONYX_SKILL_MARKDOWN = "---\nname: onyx\ndescription: Drive the Onyx auto research workflow end-to-end. Use when asked to start, resume, or continue Onyx experiments, run auto research, optimize a metric, work on an Onyx branch, /onyx anything, or keep the Onyx platform updated from local research. Handles setup, the autonomous experiment loop, and recording every attempt — successful or failed — to the Onyx platform (queued in a local outbox when offline).\n---\n\n# Onyx Research\n\nDrive an autonomous research loop using the `onyx` CLI as the substrate. You own reasoning, edits, commits, durable notes, and the experiment records the Onyx platform tracks.\n\n## Setup\n\n1. Ask (or infer):\n   - **Goal**\n   - **Evaluation**\n   - **Metric**, **unit**, **direction** (`maximize` / `minimize`)\n   - **Files in scope**\n   - **Constraints**\n   - **Stop conditions** - eg. `stop after N iterations`, `for 30 minutes`, `until <condition>`, default is no stop condition, loop forever until manually stopped by user\n2. `onyx branch create --name <slug> --metric <name> --unit <unit> --direction <maximize/minimize> --description <goal>`\n   - Add `--project-path <projectPath>` when the Onyx project is scoped to a subdirectory.\n3. Read the source files. Understand the workload deeply before writing anything.\n4. Write `<projectPath>/onyx/onyx.md` and `<projectPath>/onyx/eval.sh` (see below). Optionally write `<projectPath>/onyx/checks.sh` when correctness constraints require it. Commit these files.\n5. Run a baseline with `onyx exp run`, then record it with `onyx exp log --description \"baseline\" --agent-notes '<json>'`, then start looping immediately.\n\n### `onyx.md`\n\nThis is the heart of the session. A fresh agent with no context should be able to read this file and run the loop effectively. Invest time making it excellent.\n\n```markdown\n# Onyx Research: <goal>\n\n## Objective\n\n<Specific description of what we're optimizing and the workload.>\n\n## Metrics\n\n- **Primary**: <name>, <unit>, <direction> - the optimization target\n- **Secondary**: - independent tradeoff monitors\n  - <name>, <unit>, <direction>\n  - <name>, <unit>, <direction>\n  - ...\n\n## How to Run\n\n`./onyx/eval.sh` - outputs `METRIC name=number` lines.\n\n## Files in Scope\n\n<Every file the agent may modify, with a brief note on what it does.>\n\n## Off Limits\n\n<What must NOT be touched.>\n\n## Constraints\n\n<Hard rules: tests must pass, no new deps, etc.>\n\n## What's Been Tried\n\n<High-level strategy notes only: key wins, dead-end THEMES, and architectural\ninsights. Do not list individual experiments here - the full per-experiment\nrecord lives in `onyx exp list` (searchable offline).>\n```\n\nUpdate `onyx.md` periodically - especially the \"What's Been Tried\" section - so resuming agents have strategic context. For the detailed record of individual attempts, rely on `onyx exp list` instead of duplicating it in `onyx.md`:\n\n- `onyx exp list --limit 20` - recent experiments (newest first) with status and metric.\n- `onyx exp list --grep <regex>` - search names, descriptions, agent notes, and output summaries; e.g. `onyx exp list --grep 'cache|memoiz'` before trying a caching idea.\n- `onyx exp list --status failed --json` - full records (agent notes included) for post-mortems.\n\nThe history cache is hydrated from the Onyx app on `onyx sync`, so after a fresh clone run `onyx sync` once to pull the cross-branch history.\n\n### `eval.sh`\n\nBash script (`set -euo pipefail`) that: pre-checks fast (syntax errors in <1s), runs the benchmark, and outputs structured lines to stdout. Keep the script fast - every second is multiplied by hundreds of experiment runs.\n\n#### Structured output\n\n- `METRIC name=value` - primary metric (must match `onyx branch create`'s `metric name`) and any secondary metrics. Parsed automatically by `onyx exp run`.\n\n#### Design the script to inform optimization\n\nThe script should output **whatever data helps you make better decisions in the next iteration.** Think about what you'll need to see after each experiment run to know where to focus:\n\n- Phase timings when the workload has distinct stages\n- Error counts, failure categories, or test names when checks can fail in different ways\n- Memory usage, cache hit rates, or other runtime diagnostics when relevant\n- Anything domain-specific that would help localize regressions or identify bottlenecks\n\nThe script runs the same code every iteration - but you can **update it during the loop** if you discover you need more signal. Add instrumentation as you learn what matters.\n\n#### Agent experiment side notes via `onyx exp log`\n\nUse `onyx exp log`'s `--agent-notes` flag to annotate each experiment run with **whatever would help the next iteration make a better decision.** Free-form key/value pairs - you decide what's worth recording. Don't repeat the description or raw output; capture what you'd lose after a context reset.\n\nAnnotate failures and crashes heavily. If you don't capture what you tried and why it failed, future iterations will waste time re-discovering the same dead ends.\n\n### `checks.sh` (optional)\n\nBash script (`set -euo pipefail`) for backpressure/correctness checks: tests, types, lint, etc. **Only create this file when the user's constraints require correctness validation** (e.g., \"tests must pass\", \"types must check\").\n\nWhen this file exists:\n\n- Runs automatically after every **passing** benchmark in `onyx exp run`.\n- If checks fail, `onyx exp run` reports it clearly - log as `checks_failed`.\n- Its execution time does **NOT** affect the primary metric.\n- A `checks_failed` result is recorded, but never becomes best.\n- Has a separate timeout (default 300s, configurable via `onyx exp run --checks-timeout <seconds>`).\n\nWhen this file does **not** exist, everything behaves exactly as before - no changes to the loop.\n\n**Keep output minimal.** Only the last 80 lines of checks output are fed back to the agent on failure. Suppress verbose progress/success output and let only errors through. This keeps context lean and helps the agent pinpoint what broke.\n\n```bash\n#!/bin/bash\nset -euo pipefail\n# Example: run tests and typecheck - suppress success output, only show errors\npnpm test --run --reporter=dot 2>&1 | tail -50\npnpm typecheck 2>&1 | grep -i error || true\n```\n\n## Loop Rules\n\n**LOOP FOREVER.** Never ask \"should I continue?\" - the user expects autonomous work.\n\n- **Primary metric is king.** Improved -> build the next experiment from that result. Worse/equal -> leave it recorded and build from the prior best instead. Secondary metrics rarely affect this.\n- **Annotate every run with `--agent-notes`.** Record what you learned - not what you did. What would help the next iteration or a fresh agent resuming this session? Notes are searchable later via `onyx exp list --grep`.\n- **Simpler is better.** Removing code for equal perf = good. Ugly complexity for tiny gain = probably not worth building on.\n- **Don't thrash.** Repeatedly returning to the same idea? Try something structurally different.\n- **Crashes:** fix if trivial, otherwise log and move on. Don't over-invest.\n- **Think longer when stuck.** Re-read source files, study the profiling data, reason about what the CPU is actually doing. The best ideas come from deep understanding, not from trying random variations.\n- **Resuming:** if `onyx.md` exists, read it + git log + `onyx status` + `onyx exp list --limit 20`, continue looping.\n\n**NEVER STOP.** The user may be away for hours. Keep going until interrupted.\n\n## Git Rules\n\nOnyx is append-only: commit every attempt forward on `onyx/{name}`. Do not use `git reset --hard`, auto-revert, or force-push. Experiment metadata is canonical in the Onyx app/API; `.git/onyx/outbox.jsonl` is only an offline retry queue.\n\n## Ideas Backlog\n\nWhen you discover complex but promising optimizations that you won't pursue right now, **append them as bullets to `onyx.ideas.md`**. Don't let good ideas get lost.\n\nOn resume (context limit, crash), check `onyx.ideas.md` - prune stale/tried entries, experiment with the rest. When all paths are exhausted, delete the file and write a final summary.\n\n## User Messages During Experiments\n\nIf the user sends a message while an experiment is running, finish the current `onyx exp run` + `onyx exp log` cycle first, then incorporate their feedback in the next iteration. Don't abandon a running experiment.\n"

package/src/lib/skill.ts

@@ -0,0 +1,50 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises"
+import { homedir } from "node:os"
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+
+import { ONYX_SKILL_MARKDOWN } from "./skill-content"
+
+export const ONYX_SKILL_NAME = "onyx"
+
+export function defaultSkillInstallRoot() {
+  return join(homedir(), ".onyx", "skills")
+}
+
+export function packagedSkillPath() {
+  return fileURLToPath(new URL("../../skills/onyx/SKILL.md", import.meta.url))
+}
+
+async function readPackagedSkill() {
+  try {
+    return await readFile(packagedSkillPath(), "utf8")
+  } catch {
+    return ONYX_SKILL_MARKDOWN
+  }
+}
+
+export async function installOnyxSkill({
+  dir,
+  quiet = false,
+}: {
+  dir?: string
+  quiet?: boolean
+} = {}) {
+  const root = dir ?? defaultSkillInstallRoot()
+  const target = join(root, ONYX_SKILL_NAME, "SKILL.md")
+  await mkdir(dirname(target), { recursive: true })
+  await writeFile(target, await readPackagedSkill(), "utf8")
+  if (!quiet) {
+    console.log(`Installed Onyx agent skill to ${target}`)
+  }
+  return target
+}
+
+export async function displaySkillPath() {
+  try {
+    await readFile(packagedSkillPath(), "utf8")
+    return packagedSkillPath()
+  } catch {
+    return "embedded:onyx"
+  }
+}

package/src/lib/sync.ts

@@ -0,0 +1,294 @@
+import type {
+  LocalResearchExperimentLoggedRecord,
+  LocalResearchBranchStartedRecord,
+  LocalResearchRecord,
+} from "../protocol"
+
+import type { Args } from "./args"
+import {
+  ApiError,
+  listProjectBranches,
+  reportExperiment,
+  resolveProject,
+  upsertBranch,
+  type ApiProject,
+} from "./api"
+import { emitEvent } from "./events"
+import { pushBranch } from "./git"
+import { applyHistorySyncUpdates, type HistorySyncUpdate } from "./history"
+import { branchMetadata } from "./markdown"
+import { branchStateKey, normalizeProjectPath } from "./project"
+import {
+  readOutbox,
+  readState,
+  rewriteOutbox,
+  writeState,
+  type CliState,
+} from "./outbox"
+
+export type FlushResult = {
+  flushed: number
+  pending: number
+  offline: boolean
+}
+
+function secondaryMetrics(record: LocalResearchExperimentLoggedRecord) {
+  const rest: Record<string, number> = { ...record.metrics }
+  delete rest[record.primaryMetricName]
+  return rest
+}
+
+async function upsertBranchFromMetadata({
+  projectId,
+  root,
+  branchName,
+  gitBranchName,
+  state,
+  args,
+}: {
+  projectId: string
+  root: string
+  branchName: string
+  gitBranchName: string
+  state: CliState
+  args: Args
+}): Promise<string> {
+  const projectPath = state.projectPath ?? ""
+  const key = branchStateKey(projectPath, branchName)
+  const cached = state.branches[key]?.branchId
+  if (cached) return cached
+
+  const meta = await branchMetadata({
+    root,
+    projectPath,
+    branchName,
+    gitBranchName,
+  })
+  const branch = await upsertBranch(
+    projectId,
+    {
+      name: branchName,
+      description: meta.description ?? undefined,
+      gitBranchName,
+      baseCommitSha: meta.baseCommitSha ?? undefined,
+      metricName: meta.metricName,
+      metricUnit: meta.metricUnit ?? undefined,
+      metricDirection: meta.metricDirection,
+    },
+    args
+  )
+  state.branches[key] = { ...state.branches[key], branchId: branch.id }
+  return branch.id
+}
+
+async function flushBranchStarted({
+  projectId,
+  record,
+  state,
+  args,
+}: {
+  projectId: string
+  record: LocalResearchBranchStartedRecord
+  state: CliState
+  args: Args
+}) {
+  if (record.projectPath !== undefined) {
+    state.projectPath = record.projectPath
+  }
+  const projectPath = state.projectPath ?? ""
+  const branch = await upsertBranch(
+    projectId,
+    {
+      name: record.name,
+      description: record.description ?? undefined,
+      gitBranchName: record.gitBranchName,
+      baseCommitSha: record.baseCommitSha ?? undefined,
+      metricName: record.metricName,
+      metricUnit: record.metricUnit ?? undefined,
+      metricDirection: record.metricDirection,
+    },
+    args
+  )
+  const key = branchStateKey(projectPath, record.name)
+  state.branches[key] = {
+    ...state.branches[key],
+    branchId: branch.id,
+    projectPath,
+    gitBranchName: record.gitBranchName,
+    baseCommitSha: record.baseCommitSha ?? null,
+    description: record.description ?? null,
+    metricName: record.metricName,
+    metricUnit: record.metricUnit ?? null,
+    metricDirection: record.metricDirection,
+  }
+}
+
+async function flushExperiment({
+  projectId,
+  root,
+  record,
+  state,
+  args,
+}: {
+  projectId: string
+  root: string
+  record: LocalResearchExperimentLoggedRecord
+  state: CliState
+  args: Args
+}): Promise<HistorySyncUpdate> {
+  if (record.projectPath !== undefined) {
+    state.projectPath = record.projectPath
+  }
+  const branchId = await upsertBranchFromMetadata({
+    projectId,
+    root,
+    branchName: record.branchName,
+    gitBranchName: record.gitBranchName,
+    state,
+    args,
+  })
+
+  const reported = await reportExperiment(
+    branchId,
+    {
+      name: record.name,
+      description: record.description ?? undefined,
+      runRef: record.runRef,
+      commitSha: record.commitSha,
+      status: record.status,
+      primaryMetricName: record.primaryMetricName,
+      primaryMetricValue: record.primaryMetricValue ?? undefined,
+      secondaryMetrics: secondaryMetrics(record),
+      artifactRefs: {},
+      agentNotes: record.agentNotes,
+      checks: record.checks ?? undefined,
+      durationMs: record.durationMs ?? undefined,
+      outputSummary: record.outputSummary ?? undefined,
+      startedAt: record.startedAt ?? undefined,
+      completedAt: record.completedAt ?? undefined,
+    },
+    args
+  )
+  return {
+    sequenceNumber: reported.sequenceNumber,
+    experimentId: reported.id,
+    branchId,
+  }
+}
+
+/**
+ * Replays the local outbox to the Onyx API. Resolves the project, pushes every
+ * referenced branch so reported commits are reachable, then upserts branches and
+ * reports experiments idempotently (server dedups by runRef). A 409 means the
+ * commit is not on the mirror yet (push/propagation lag) and is retried on the
+ * next flush; any other error keeps the record queued and is surfaced. Offline
+ * (project unresolvable) leaves the outbox untouched.
+ */
+export async function flushOutbox(
+  root: string,
+  args: Args,
+  options: { quiet?: boolean } = {}
+): Promise<FlushResult> {
+  const { records, corrupt } = await readOutbox(root)
+  if (corrupt > 0 && !options.quiet) {
+    console.warn(`Skipped ${corrupt} unreadable outbox record(s).`)
+  }
+  if (records.length === 0) {
+    return { flushed: 0, pending: 0, offline: false }
+  }
+
+  const state = await readState(root)
+  const requestedProjectPath = normalizeProjectPath(
+    args.options["project-path"]
+  )
+  const queuedProjectPath = records.find(
+    (record) => record.projectPath !== undefined
+  )?.projectPath
+  state.projectPath =
+    requestedProjectPath || queuedProjectPath || state.projectPath
+  await writeState(root, state)
+
+  let project: ApiProject
+  try {
+    project = await resolveProject(root, args)
+  } catch (error) {
+    if (!options.quiet) {
+      console.log(
+        `${records.length} record(s) queued locally; not synced (${
+          error instanceof Error ? error.message : String(error)
+        })`
+      )
+    }
+    return { flushed: 0, pending: records.length, offline: true }
+  }
+
+  state.projectId = project.id
+
+  // Push every referenced branch up front so reported commits are reachable.
+  for (const branch of new Set(records.map((record) => record.gitBranchName))) {
+    try {
+      await pushBranch(root, branch)
+    } catch {
+      // Keep going: the report 409s and is retried if the commit is unreachable.
+    }
+  }
+
+  // Pre-populate branch ids so concurrently-created branches resolve without upsert.
+  try {
+    for (const branch of await listProjectBranches(project.id, args)) {
+      const key = branchStateKey(state.projectPath ?? "", branch.name)
+      state.branches[key] = { ...state.branches[key], branchId: branch.id }
+    }
+  } catch {
+    // best-effort
+  }
+
+  const remaining: LocalResearchRecord[] = []
+  const historyUpdates = new Map<string, HistorySyncUpdate>()
+  let flushed = 0
+
+  for (const record of records) {
+    try {
+      if (record.type === "branch_started") {
+        await flushBranchStarted({ projectId: project.id, record, state, args })
+      } else {
+        const update = await flushExperiment({
+          projectId: project.id,
+          root,
+          record,
+          state,
+          args,
+        })
+        historyUpdates.set(record.runRef, update)
+      }
+      flushed += 1
+    } catch (error) {
+      if (!(error instanceof ApiError) || error.status !== 409) {
+        if (!options.quiet) {
+          console.warn(
+            `Keeping queued record after error: ${
+              error instanceof Error ? error.message : String(error)
+            }`
+          )
+        }
+      }
+      remaining.push(record)
+    }
+  }
+
+  await rewriteOutbox(root, remaining)
+  await writeState(root, state)
+  // Stamp server-assigned sequence numbers onto the local history cache so
+  // the TUI shows them immediately. Best-effort: hydration also covers this.
+  await applyHistorySyncUpdates(root, historyUpdates).catch(() => {})
+  await emitEvent(root, {
+    type: "flush_finished",
+    message: `synced ${flushed}, pending ${remaining.length}`,
+  })
+
+  if (!options.quiet) {
+    console.log(`Synced ${flushed} record(s); ${remaining.length} pending.`)
+  }
+
+  return { flushed, pending: remaining.length, offline: false }
+}