ada-agent 0.2.0 → 0.3.0

package/skills/skeleton-loader/SKILL.md

@@ -1,23 +1,23 @@
----
-name: skeleton-loader
-description: Build loading skeletons and shimmer that mirror the final layout to reduce perceived wait and CLS.
-category: ui-design
----
-
-# Skeleton Loader
-
-Reach for this when content takes a beat to load and a spinner would feel slow or cause layout shift — skeletons preview structure so the page feels fast and stable.
-
-1. Mirror the real layout: build the skeleton from the same component with placeholder blocks at the actual sizes/positions, so swapping in data causes zero shift (protects CLS).
-2. Skeleton-ize structure, not pixels: a few grey rounded blocks for title/avatar/lines — vary line widths (last line ~60%) so it reads as text, not a wireframe of every glyph.
-3. Animate with a restrained shimmer: a slow gradient sweep (~1.5–2s linear, looping) or a gentle opacity pulse — subtle, low-contrast, never a strobing distraction.
-4. Use the skeleton only past a perception threshold: render instantly when content is likely <~200ms? show nothing or the cached value; show the skeleton when you expect a real wait, and avoid flash-of-skeleton for sub-100ms loads.
-5. Transition out smoothly: crossfade skeleton → content (~150ms) rather than a hard pop, and stagger if many items resolve together.
-6. Honor `prefers-reduced-motion` by replacing the sweep with a static muted block, and keep the skeleton color derived from your surface/muted tokens for theme + dark-mode correctness.
-
-## Rules
-- Skeleton dimensions must equal final dimensions — if the content reflows on load, the skeleton failed its one job.
-- Keep shimmer low-contrast and slow; a fast, high-contrast sweep is more annoying than a spinner.
-- Don't skeleton a whole page when only one region is async — load shell + chrome instantly, skeleton just the pending part.
-- Avoid skeleton flicker: gate on a short delay so fast responses never flash a placeholder.
-- Build from muted/surface tokens so it adapts to light/dark automatically — no hard-coded greys.
+---
+name: skeleton-loader
+description: Build loading skeletons and shimmer that mirror the final layout to reduce perceived wait and CLS.
+category: ui-design
+---
+
+# Skeleton Loader
+
+Reach for this when content takes a beat to load and a spinner would feel slow or cause layout shift — skeletons preview structure so the page feels fast and stable.
+
+1. Mirror the real layout: build the skeleton from the same component with placeholder blocks at the actual sizes/positions, so swapping in data causes zero shift (protects CLS).
+2. Skeleton-ize structure, not pixels: a few grey rounded blocks for title/avatar/lines — vary line widths (last line ~60%) so it reads as text, not a wireframe of every glyph.
+3. Animate with a restrained shimmer: a slow gradient sweep (~1.5–2s linear, looping) or a gentle opacity pulse — subtle, low-contrast, never a strobing distraction.
+4. Use the skeleton only past a perception threshold: render instantly when content is likely <~200ms? show nothing or the cached value; show the skeleton when you expect a real wait, and avoid flash-of-skeleton for sub-100ms loads.
+5. Transition out smoothly: crossfade skeleton → content (~150ms) rather than a hard pop, and stagger if many items resolve together.
+6. Honor `prefers-reduced-motion` by replacing the sweep with a static muted block, and keep the skeleton color derived from your surface/muted tokens for theme + dark-mode correctness.
+
+## Rules
+- Skeleton dimensions must equal final dimensions — if the content reflows on load, the skeleton failed its one job.
+- Keep shimmer low-contrast and slow; a fast, high-contrast sweep is more annoying than a spinner.
+- Don't skeleton a whole page when only one region is async — load shell + chrome instantly, skeleton just the pending part.
+- Avoid skeleton flicker: gate on a short delay so fast responses never flash a placeholder.
+- Build from muted/surface tokens so it adapts to light/dark automatically — no hard-coded greys.

package/skills/tailwind-theme/SKILL.md

@@ -1,24 +1,24 @@
----
-name: tailwind-theme
-description: Set up Tailwind with a custom token-driven theme so utilities map to your design system, not defaults
-category: ui-design
----
-
-# Tailwind Theme
-
-Use this when a Tailwind project still looks like stock Tailwind — default grays, `blue-500`, `shadow-md` everywhere. The fix is wiring Tailwind to your tokens so utility classes carry your brand.
-
-1. Define your palette/space/type/radius as CSS custom properties on `:root` (and a dark override), then point Tailwind at them. In v4, do this in CSS via `@theme { --color-accent: …; --radius-lg: …; }`.
-2. Map semantic names into the theme: `bg-surface`, `text-muted`, `border-subtle`, `bg-accent` — so markup reads by role and a re-theme is a token edit, not a find-replace across components.
-3. Replace, don't extend-and-ignore, the defaults you won't use: prune the stock gray ramp and arbitrary blues so nobody reaches for `text-gray-500` and bypasses your system.
-4. Set a real type scale and `fontFamily` from your fonts; configure `--leading-*` and `--tracking-*` so `text-2xl` etc. carry intentional line-height, not Tailwind's generic defaults.
-5. Build repeated patterns as components (React/Astro/Svelte) or `@apply` recipes for true primitives (`.btn`), not by copy-pasting 14 utility classes per button.
-6. Lean on Tailwind's modern features intentionally: container queries (`@container`), `data-*`/`aria-*` variants for state, and the `dark:` variant driven by your `[data-theme]` strategy.
-7. Add `prettier-plugin-tailwindcss` for canonical class order and an ESLint rule to flag arbitrary values (`w-[13px]`) that signal an off-system value.
-
-## Rules
-- Utilities must resolve to your tokens; if `bg-accent` doesn't exist, the theme isn't wired up.
-- Prune unused default colors so the stock palette can't be used by accident.
-- Extract a component or `@apply` recipe once a class string repeats; don't shotgun utilities.
-- Arbitrary values (`p-[13px]`, `text-[#3a3a3a]`) are escape hatches — flag and minimize them.
-- Drive `dark:` from the same token strategy as the rest of the system, not a separate color set.
+---
+name: tailwind-theme
+description: Set up Tailwind with a custom token-driven theme so utilities map to your design system, not defaults
+category: ui-design
+---
+
+# Tailwind Theme
+
+Use this when a Tailwind project still looks like stock Tailwind — default grays, `blue-500`, `shadow-md` everywhere. The fix is wiring Tailwind to your tokens so utility classes carry your brand.
+
+1. Define your palette/space/type/radius as CSS custom properties on `:root` (and a dark override), then point Tailwind at them. In v4, do this in CSS via `@theme { --color-accent: …; --radius-lg: …; }`.
+2. Map semantic names into the theme: `bg-surface`, `text-muted`, `border-subtle`, `bg-accent` — so markup reads by role and a re-theme is a token edit, not a find-replace across components.
+3. Replace, don't extend-and-ignore, the defaults you won't use: prune the stock gray ramp and arbitrary blues so nobody reaches for `text-gray-500` and bypasses your system.
+4. Set a real type scale and `fontFamily` from your fonts; configure `--leading-*` and `--tracking-*` so `text-2xl` etc. carry intentional line-height, not Tailwind's generic defaults.
+5. Build repeated patterns as components (React/Astro/Svelte) or `@apply` recipes for true primitives (`.btn`), not by copy-pasting 14 utility classes per button.
+6. Lean on Tailwind's modern features intentionally: container queries (`@container`), `data-*`/`aria-*` variants for state, and the `dark:` variant driven by your `[data-theme]` strategy.
+7. Add `prettier-plugin-tailwindcss` for canonical class order and an ESLint rule to flag arbitrary values (`w-[13px]`) that signal an off-system value.
+
+## Rules
+- Utilities must resolve to your tokens; if `bg-accent` doesn't exist, the theme isn't wired up.
+- Prune unused default colors so the stock palette can't be used by accident.
+- Extract a component or `@apply` recipe once a class string repeats; don't shotgun utilities.
+- Arbitrary values (`p-[13px]`, `text-[#3a3a3a]`) are escape hatches — flag and minimize them.
+- Drive `dark:` from the same token strategy as the rest of the system, not a separate color set.

package/skills/typography/SKILL.md

@@ -1,24 +1,24 @@
----
-name: typography
-description: Set an intentional modular type scale and font pairing with deliberate rhythm, measure, and hierarchy
-category: ui-design
----
-
-# Typography
-
-Reach for this when text feels flat or noisy — everything the same weight, headings barely larger than body, lines too long to read. Typography carries most of a UI's perceived quality.
-
-1. Pick a scale ratio and generate sizes from one base: 1.2 (minor third) for dense product UI, 1.25–1.333 for marketing. Use `clamp()` for fluid headings: `clamp(2rem, 1.2rem + 3vw, 3.5rem)`.
-2. Pair at most two families with real contrast in role — e.g. a characterful display serif (Fraunces) over a neutral workhorse sans (Inter), or one superfamily across weights. More than two fonts reads as chaos.
-3. Set body deliberately: 15–18px, `line-height` 1.5–1.65, and constrain measure to 60–75ch with `max-width: 65ch`. Long lines are the most common readability failure.
-4. Build hierarchy with weight and size and color together — not size alone. A muted `--text-muted` for captions, a heavier 600–700 for headings, tight tracking (`-0.02em`) on large display text.
-5. Tighten leading as size grows (headings 1.1–1.2, body 1.5) and add `text-wrap: balance` on headings, `pretty` on paragraphs to kill orphans.
-6. Enable OpenType features that fit the context: `font-feature-settings` for tabular numerals in tables/dashboards, ligatures for prose; `font-variant-numeric: tabular-nums` stops number jitter.
-7. Verify the rendered rhythm at real sizes and viewports, not in the abstract — print a paragraph plus h1–h4 and adjust.
-
-## Rules
-- Two type families maximum; if you need a third role, change weight, not font.
-- Body measure 60–75ch; never let prose run the full container width.
-- Pair every font-size with an intentional line-height — don't inherit a global 1.5 onto display text.
-- Use tabular numerals anywhere numbers align in columns or update live.
-- Establish scale steps as tokens; reaching for an off-scale `font-size: 19px` is a smell.
+---
+name: typography
+description: Set an intentional modular type scale and font pairing with deliberate rhythm, measure, and hierarchy
+category: ui-design
+---
+
+# Typography
+
+Reach for this when text feels flat or noisy — everything the same weight, headings barely larger than body, lines too long to read. Typography carries most of a UI's perceived quality.
+
+1. Pick a scale ratio and generate sizes from one base: 1.2 (minor third) for dense product UI, 1.25–1.333 for marketing. Use `clamp()` for fluid headings: `clamp(2rem, 1.2rem + 3vw, 3.5rem)`.
+2. Pair at most two families with real contrast in role — e.g. a characterful display serif (Fraunces) over a neutral workhorse sans (Inter), or one superfamily across weights. More than two fonts reads as chaos.
+3. Set body deliberately: 15–18px, `line-height` 1.5–1.65, and constrain measure to 60–75ch with `max-width: 65ch`. Long lines are the most common readability failure.
+4. Build hierarchy with weight and size and color together — not size alone. A muted `--text-muted` for captions, a heavier 600–700 for headings, tight tracking (`-0.02em`) on large display text.
+5. Tighten leading as size grows (headings 1.1–1.2, body 1.5) and add `text-wrap: balance` on headings, `pretty` on paragraphs to kill orphans.
+6. Enable OpenType features that fit the context: `font-feature-settings` for tabular numerals in tables/dashboards, ligatures for prose; `font-variant-numeric: tabular-nums` stops number jitter.
+7. Verify the rendered rhythm at real sizes and viewports, not in the abstract — print a paragraph plus h1–h4 and adjust.
+
+## Rules
+- Two type families maximum; if you need a third role, change weight, not font.
+- Body measure 60–75ch; never let prose run the full container width.
+- Pair every font-size with an intentional line-height — don't inherit a global 1.5 onto display text.
+- Use tabular numerals anywhere numbers align in columns or update live.
+- Establish scale steps as tokens; reaching for an off-scale `font-size: 19px` is a smell.

package/skills/ui-polish/SKILL.md

@@ -1,24 +1,24 @@
----
-name: ui-polish
-description: Elevate a rough but working UI — fix spacing, alignment, hierarchy, and the small details that read as quality
-category: ui-design
----
-
-# UI Polish
-
-Reach for this on a UI that functions but feels amateur — cramped, misaligned, flat. Polish is mostly subtraction and precision, not adding more.
-
-1. Establish a spacing rhythm: snap every margin/padding/gap to the 4px (or 8px) scale, and make whitespace intentional — generous around groups, tight within them. Inconsistent gaps are the #1 tell.
-2. Fix alignment to an actual grid: align edges and baselines, give content a `max-width` and consistent gutters, and make optical adjustments (icons often need a nudge to look centered).
-3. Sharpen hierarchy: there should be an obvious first, second, and third thing on every screen. Use size, weight, and `--text-muted` color to demote secondary text instead of cramming everything at one level.
-4. Tame the details: soften pure-black text to a near-black, swap harsh `0 1px 2px #000` shadows for layered low-alpha ones, align radii across siblings, and ensure border colors are subtle (low-contrast neutrals).
-5. Polish interaction: add `:focus-visible` rings, hover/active feedback, and tasteful transitions (120–200ms, `ease-out`) on color and transform — never on `width`/`height` (use `transform`).
-6. Handle the real states: empty, loading (skeletons over spinners), error, and long-content overflow. Unpolished UIs only ever show the happy path.
-7. Do a final squint test and a 50%-zoom pass — blurred vision exposes weak hierarchy and ragged alignment instantly.
-
-## Rules
-- Every spacing value is on the scale; an unexplained `padding: 13px` is a defect.
-- Increase contrast in hierarchy, decrease it in chrome — borders and shadows should whisper.
-- Animate `transform`/`opacity` only; transitions 120–250ms with `ease-out`/custom cubic-bezier.
-- Never ship without focus-visible, hover, empty, and loading states.
-- When in doubt, remove an element or add whitespace before adding decoration.
+---
+name: ui-polish
+description: Elevate a rough but working UI — fix spacing, alignment, hierarchy, and the small details that read as quality
+category: ui-design
+---
+
+# UI Polish
+
+Reach for this on a UI that functions but feels amateur — cramped, misaligned, flat. Polish is mostly subtraction and precision, not adding more.
+
+1. Establish a spacing rhythm: snap every margin/padding/gap to the 4px (or 8px) scale, and make whitespace intentional — generous around groups, tight within them. Inconsistent gaps are the #1 tell.
+2. Fix alignment to an actual grid: align edges and baselines, give content a `max-width` and consistent gutters, and make optical adjustments (icons often need a nudge to look centered).
+3. Sharpen hierarchy: there should be an obvious first, second, and third thing on every screen. Use size, weight, and `--text-muted` color to demote secondary text instead of cramming everything at one level.
+4. Tame the details: soften pure-black text to a near-black, swap harsh `0 1px 2px #000` shadows for layered low-alpha ones, align radii across siblings, and ensure border colors are subtle (low-contrast neutrals).
+5. Polish interaction: add `:focus-visible` rings, hover/active feedback, and tasteful transitions (120–200ms, `ease-out`) on color and transform — never on `width`/`height` (use `transform`).
+6. Handle the real states: empty, loading (skeletons over spinners), error, and long-content overflow. Unpolished UIs only ever show the happy path.
+7. Do a final squint test and a 50%-zoom pass — blurred vision exposes weak hierarchy and ragged alignment instantly.
+
+## Rules
+- Every spacing value is on the scale; an unexplained `padding: 13px` is a defect.
+- Increase contrast in hierarchy, decrease it in chrome — borders and shadows should whisper.
+- Animate `transform`/`opacity` only; transitions 120–250ms with `ease-out`/custom cubic-bezier.
+- Never ship without focus-visible, hover, empty, and loading states.
+- When in doubt, remove an element or add whitespace before adding decoration.

package/skills/ui-review/SKILL.md

@@ -1,24 +1,24 @@
----
-name: ui-review
-description: Critique a UI for visual quality, consistency, and hierarchy, returning specific, prioritized fixes
-category: ui-design
----
-
-# UI Review
-
-Use this to evaluate an existing screen with a senior designer's eye and produce concrete, actionable critique — not "looks good" but "the h2 and body are too close in size; bump the scale ratio to 1.25."
-
-1. Read intent first: what is this screen for, what's the one primary action? Judge everything against whether the design serves that goal and points the eye to it.
-2. Check hierarchy with the squint test: blur your vision (or zoom to 50%) and confirm the most important element dominates. If everything competes, that's finding #1.
-3. Audit consistency: collect the distinct spacings, font sizes, colors, radii, and shadows in play. Off-scale or near-duplicate values (15px vs 16px, two almost-equal grays) are concrete defects to list.
-4. Measure the fundamentals: contrast ratios on text (AA 4.5:1), body measure (60–75ch), alignment to a grid, and spacing rhythm. Flag exact violations with the failing value.
-5. Inspect states and motion: are focus-visible, hover, empty, loading, and error handled? Are transitions tasteful (120–250ms, eased) or janky/missing?
-6. Assess the aesthetic: is there a point of view, or does it read templated? Name the one change that would most raise perceived quality.
-7. Return findings ranked by impact, each as observation → why it hurts → specific fix, separating must-fix from nice-to-have.
-
-## Rules
-- Every critique is specific and actionable — name the element, the failing value, and the fix.
-- Lead with hierarchy and consistency; they drive perceived quality more than color choice.
-- Cite measurable thresholds (contrast, measure, spacing scale) instead of vibes.
-- Prioritize: 3 high-impact fixes beat 30 nitpicks.
-- Acknowledge what works so good decisions survive the next iteration.
+---
+name: ui-review
+description: Critique a UI for visual quality, consistency, and hierarchy, returning specific, prioritized fixes
+category: ui-design
+---
+
+# UI Review
+
+Use this to evaluate an existing screen with a senior designer's eye and produce concrete, actionable critique — not "looks good" but "the h2 and body are too close in size; bump the scale ratio to 1.25."
+
+1. Read intent first: what is this screen for, what's the one primary action? Judge everything against whether the design serves that goal and points the eye to it.
+2. Check hierarchy with the squint test: blur your vision (or zoom to 50%) and confirm the most important element dominates. If everything competes, that's finding #1.
+3. Audit consistency: collect the distinct spacings, font sizes, colors, radii, and shadows in play. Off-scale or near-duplicate values (15px vs 16px, two almost-equal grays) are concrete defects to list.
+4. Measure the fundamentals: contrast ratios on text (AA 4.5:1), body measure (60–75ch), alignment to a grid, and spacing rhythm. Flag exact violations with the failing value.
+5. Inspect states and motion: are focus-visible, hover, empty, loading, and error handled? Are transitions tasteful (120–250ms, eased) or janky/missing?
+6. Assess the aesthetic: is there a point of view, or does it read templated? Name the one change that would most raise perceived quality.
+7. Return findings ranked by impact, each as observation → why it hurts → specific fix, separating must-fix from nice-to-have.
+
+## Rules
+- Every critique is specific and actionable — name the element, the failing value, and the fix.
+- Lead with hierarchy and consistency; they drive perceived quality more than color choice.
+- Cite measurable thresholds (contrast, measure, spacing scale) instead of vibes.
+- Prioritize: 3 high-impact fixes beat 30 nitpicks.
+- Acknowledge what works so good decisions survive the next iteration.

package/skills/web-fonts/SKILL.md

@@ -1,24 +1,24 @@
----
-name: web-fonts
-description: Load and pair web fonts performantly — subset, preload, self-host, and avoid FOUT/FOIT and layout shift
-category: ui-design
----
-
-# Web Fonts
-
-Use this when adding or fixing custom fonts so they look right *and* load fast. Fonts are often a page's heaviest render-blocking asset and a top cause of layout shift.
-
-1. Prefer variable fonts in `woff2` only — one file covers all weights, drops requests, and `woff2` is the smallest format every modern browser supports.
-2. Self-host instead of linking Google Fonts: it removes a third-party round-trip and the privacy/consent overhead, and lets you control caching and `font-display`.
-3. Subset aggressively — strip to the scripts/glyphs you use (e.g. latin + latin-ext) with `glyphhanger`/`fonttools`; a full font can shrink 70%+, cutting first paint.
-4. `preload` the one or two critical fonts (the body and primary heading face) with `<link rel="preload" as="font" type="font/woff2" crossorigin>`; don't preload every weight.
-5. Set `font-display: swap` to render text immediately in a fallback, then tune the fallback metrics with `size-adjust`, `ascent-override`, and `descent-override` (or Next/Fontsource defaults) so the swap causes near-zero CLS.
-6. Define a real fallback stack matched in metrics to the web font (`"Inter", system-ui, sans-serif`) so the pre-swap render already looks close.
-7. Measure: confirm in DevTools that fonts are `woff2`, preloaded, swapped, and that the layout-shift score stays near zero after they load.
-
-## Rules
-- `woff2` only, variable font when available; never serve `ttf`/`otf`/multiple static weights.
-- Self-host critical fonts; reserve external CDNs for non-critical or fallback cases.
-- Preload only the 1–2 above-the-fold faces — preloading everything defeats the purpose.
-- `font-display: swap` plus metric-overridden fallbacks to keep CLS ≈ 0.
-- Subset to the glyphs you actually render; ship no unused scripts.
+---
+name: web-fonts
+description: Load and pair web fonts performantly — subset, preload, self-host, and avoid FOUT/FOIT and layout shift
+category: ui-design
+---
+
+# Web Fonts
+
+Use this when adding or fixing custom fonts so they look right *and* load fast. Fonts are often a page's heaviest render-blocking asset and a top cause of layout shift.
+
+1. Prefer variable fonts in `woff2` only — one file covers all weights, drops requests, and `woff2` is the smallest format every modern browser supports.
+2. Self-host instead of linking Google Fonts: it removes a third-party round-trip and the privacy/consent overhead, and lets you control caching and `font-display`.
+3. Subset aggressively — strip to the scripts/glyphs you use (e.g. latin + latin-ext) with `glyphhanger`/`fonttools`; a full font can shrink 70%+, cutting first paint.
+4. `preload` the one or two critical fonts (the body and primary heading face) with `<link rel="preload" as="font" type="font/woff2" crossorigin>`; don't preload every weight.
+5. Set `font-display: swap` to render text immediately in a fallback, then tune the fallback metrics with `size-adjust`, `ascent-override`, and `descent-override` (or Next/Fontsource defaults) so the swap causes near-zero CLS.
+6. Define a real fallback stack matched in metrics to the web font (`"Inter", system-ui, sans-serif`) so the pre-swap render already looks close.
+7. Measure: confirm in DevTools that fonts are `woff2`, preloaded, swapped, and that the layout-shift score stays near zero after they load.
+
+## Rules
+- `woff2` only, variable font when available; never serve `ttf`/`otf`/multiple static weights.
+- Self-host critical fonts; reserve external CDNs for non-critical or fallback cases.
+- Preload only the 1–2 above-the-fold faces — preloading everything defeats the purpose.
+- `font-display: swap` plus metric-overridden fallbacks to keep CLS ≈ 0.
+- Subset to the glyphs you actually render; ship no unused scripts.

package/src/client/autostart.ts

@@ -0,0 +1,93 @@
+// Auto-start the ada backend if it isn't reachable. So new users running `ada` for the first time
+// don't have to also remember "start ada-server in another terminal." If the configured backend URL
+// is remote (not localhost), we DON'T spawn anything — the user clearly meant to point at a remote.
+// The spawned child is killed when this process exits.
+
+import { spawn } from "node:child_process";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const LOCAL_HOSTS = new Set(["localhost", "127.0.0.1", "0.0.0.0", "::1", "[::1]"]);
+
+/** True if the backend URL points at this machine — the only case we auto-spawn for. */
+export function isLocalBackend(backendUrl: string): boolean {
+  try {
+    return LOCAL_HOSTS.has(new URL(backendUrl).hostname);
+  } catch {
+    return false;
+  }
+}
+
+/** Probe the backend's /health. The URL passed in is `<base>/v1`; /health is at the base, not /v1. */
+export function healthUrl(backendUrl: string): string {
+  try {
+    const u = new URL(backendUrl);
+    u.pathname = "/health";
+    u.search = "";
+    return u.toString();
+  } catch {
+    return `${backendUrl.replace(/\/+$/, "").replace(/\/v\d+$/, "")}/health`;
+  }
+}
+
+async function probe(url: string, timeoutMs = 800): Promise<boolean> {
+  try {
+    const res = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+/** Resolved path to bin/ada-server.mjs (sibling of bin/ada.mjs, packaged in the npm tarball). */
+function serverBin(): string {
+  return resolve(fileURLToPath(import.meta.url), "..", "..", "..", "bin", "ada-server.mjs");
+}
+
+/**
+ * If the backend isn't responding (and the URL is local), spawn `ada-server` as a child process and
+ * wait up to `waitMs` for /health to come up. Returns `"running"` if already alive, `"started"` if
+ * we spawned it, `"remote"` if the URL is remote (skipped), or `"failed"` if it didn't come up in
+ * time. Sets `process.on(...)` handlers so the child dies with us.
+ */
+export async function ensureBackend(backendUrl: string, opts?: { quiet?: boolean; waitMs?: number }): Promise<"running" | "started" | "remote" | "failed"> {
+  const probeUrl = healthUrl(backendUrl);
+  if (await probe(probeUrl)) return "running";
+  if (!isLocalBackend(backendUrl)) return "remote";
+
+  if (!opts?.quiet) process.stderr.write("\x1b[2mstarting ada-server…\x1b[0m ");
+  const child = spawn(process.execPath, [serverBin()], { stdio: ["ignore", "ignore", "ignore"], detached: false });
+  child.unref(); // don't keep parent alive once parent's own work finishes
+  const killChild = (): void => {
+    try {
+      if (!child.killed) child.kill();
+    } catch {
+      /* ignore */
+    }
+  };
+  process.once("exit", killChild);
+  process.once("SIGINT", () => {
+    killChild();
+    process.exit(130);
+  });
+  process.once("SIGTERM", () => {
+    killChild();
+    process.exit(143);
+  });
+  child.once("error", () => {
+    /* surfaced via the probe loop's timeout */
+  });
+
+  const deadline = Date.now() + (opts?.waitMs ?? 5000);
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, 150));
+    if (await probe(probeUrl, 400)) {
+      if (!opts?.quiet) process.stderr.write("\x1b[32mok\x1b[0m\n");
+      return "started";
+    }
+    if (child.exitCode != null) break; // child died — no point waiting more
+  }
+  if (!opts?.quiet) process.stderr.write("\x1b[31mfailed\x1b[0m\n");
+  killChild();
+  return "failed";
+}