@sibylline-labs/eris 0.0.0-stage → 0.3.0

package/plugins/yak/login.ts

@@ -0,0 +1,300 @@
+/**
+ * login.ts — `eris login` and `eris logout`, loaded only when one dispatches
+ * (the manifest is ./index.ts).
+ *
+ * `eris login` is an RFC 8628 device-authorization client. It starts a grant at
+ * `<url>/v1/device/code`, shows the user code and the verification URI (and
+ * opens a browser when it can), then polls `<url>/v1/device/token` until the
+ * code is approved, denied or expired. The bearer it is handed goes into
+ * `~/.eris/yaks.json`, the one file `eris yak` reads (./yak-identity.ts), with
+ * the url beside it. The url comes from `resolveUrl`, the one resolver `eris
+ * yak` also reads: `--url`, else `ERIS_YAKS_URL`, else the file's own `url`,
+ * else `DEFAULT_YAKS_URL`, so there is always an endpoint (the parser refuses
+ * an empty `--url`).
+ *
+ * `eris logout` removes the token from that file and keeps the url. No route
+ * lets a bearer revoke itself, so the token stays valid server-side until it is
+ * revoked from the dashboard's API tokens settings; the command says so.
+ *
+ * Invariants:
+ *   - Neither the device code nor the bearer is ever written to stdout or
+ *     stderr. The user code is the one value shown, and it is not a secret on
+ *     its own.
+ *   - A grant that does not end approved writes nothing: the file is replaced
+ *     once, after a token has been received, through `writeYaksFileConfig`
+ *     (created 0600, renamed into place).
+ *   - The poll interval only grows: `slow_down` raises it for every later poll
+ *     (to the interval it carries, else by 5 s); a 429 waits out `retry-after`
+ *     for one poll. The code's `expires_in` ends the loop locally even if the
+ *     server never says `expired_token`.
+ *   - Two error shapes are read: RFC 6749's `{error: "<code>"}` (every 400) and
+ *     the gateway's `{error: {code, message}}` (429, 503). A 5xx or a dropped
+ *     connection while polling is retried up to `MAX_TRANSIENT` times in a
+ *     row, so a blip after the user approved does not throw the approval away.
+ *   - Text from the server is shown only after control characters are
+ *     stripped, so a response cannot drive the terminal.
+ */
+
+import { hostname as osHostname } from "node:os";
+import { renderFailureBlock, renderWarnLines, readArgs, type VerbContext } from "../../src/cli/plugin";
+import plugin from "./index";
+import { DEFAULT_YAKS_URL, readYaksFileConfig, resolveUrl, runBounded, writeYaksFileConfig, yaksConfigPath } from "./yak-identity";
+import { promises as fs } from "node:fs";
+
+/** The `docs/ERRORS.md` slugs this module raises (`tests/errors-doc.test.ts`). */
+export type LoginSlug =
+  | "login-unreachable"
+  | "login-refused"
+  | "login-denied"
+  | "login-expired"
+  | "login-env-token-overrides";
+
+const DEVICE_AUTHORIZATION_PATH = "/v1/device/code";
+const DEVICE_TOKEN_PATH = "/v1/device/token";
+const DEVICE_CODE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code";
+/** RFC 8628 §3.5: what `slow_down` adds when it carries no interval. */
+const SLOW_DOWN_STEP_MS = 5_000;
+/** Consecutive 5xx or dropped polls tolerated before giving up. */
+const MAX_TRANSIENT = 3;
+/** One request's whole exchange, headers and body. */
+const REQUEST_TIMEOUT_MS = 15_000;
+/** The gateway caps a device label at 128 characters. */
+const MAX_LABEL = 128;
+
+export const LOGIN_USAGE = `Usage: eris login [--url <url>] [--no-browser]
+
+Sign this machine in with a device code: approve the code shown here in your
+browser, and the token is written to ~/.eris/yaks.json (mode 0600), where
+'eris yak' reads it. ERIS_YAKS_TOKEN, when set, still wins over the file.
+
+  --url <url>    the endpoint (default: $ERIS_YAKS_URL, then the url
+                 already in ~/.eris/yaks.json, then ${DEFAULT_YAKS_URL})
+  --no-browser   print the link without trying to open a browser
+`;
+
+export const LOGOUT_USAGE = `Usage: eris logout
+
+Remove this machine's token from ~/.eris/yaks.json, keeping the url. The token
+stays valid until it is revoked under Settings > API Tokens.
+`;
+
+export interface LoginDeps {
+  home?: string;
+  hostname?: () => string;
+  now?: () => number;
+  sleep?: (ms: number) => Promise<void>;
+  /** Open `url` in a browser, best effort. The default does so only when
+   *  stderr is a terminal. */
+  openBrowser?: (url: string) => Promise<void>;
+}
+
+type Grant = {
+  deviceCode: string;
+  userCode: string;
+  verificationUri: string;
+  expiresInMs: number;
+  intervalMs: number;
+};
+
+type Exchange = { kind: "response"; status: number; headers: Headers; body: unknown } | { kind: "unreachable"; reason: string };
+
+/** Drop control characters, so text a server sent cannot drive the terminal. */
+function printable(text: string): string {
+  return text.replace(/[\u0000-\u001f\u007f-\u009f]/g, "");
+}
+
+/** The error code from either shape: RFC `{error: "<code>"}` or the gateway's `{error: {code}}`. */
+function errorCode(status: number, body: unknown): string {
+  if (typeof body === "object" && body !== null) {
+    const error = (body as Record<string, unknown>).error;
+    if (typeof error === "string") return printable(error);
+    if (typeof error === "object" && error !== null) {
+      const { code, message } = error as Record<string, unknown>;
+      if (typeof code === "string") return printable(typeof message === "string" ? `${code}: ${message}` : code);
+    }
+  }
+  return `HTTP ${status}`;
+}
+
+async function post(url: string, form: Record<string, string>): Promise<Exchange> {
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
+      body: new URLSearchParams(form).toString(),
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    let body: unknown = null;
+    try {
+      body = await res.json();
+    } catch {
+      // A body that is not JSON reads as no body; the status still decides.
+    }
+    return { kind: "response", status: res.status, headers: res.headers, body };
+  } catch (err) {
+    const name = (err as { name?: string }).name;
+    return { kind: "unreachable", reason: name === "TimeoutError" ? `no answer within ${REQUEST_TIMEOUT_MS / 1000}s` : printable((err as Error).message) };
+  }
+}
+
+function readGrant(body: unknown): Grant | null {
+  if (typeof body !== "object" || body === null) return null;
+  const b = body as Record<string, unknown>;
+  const { device_code, user_code, verification_uri, verification_uri_complete, expires_in, interval } = b;
+  if (typeof device_code !== "string" || typeof user_code !== "string" || typeof verification_uri !== "string") return null;
+  if (typeof expires_in !== "number" || !(expires_in > 0)) return null;
+  return {
+    deviceCode: device_code,
+    userCode: printable(user_code),
+    verificationUri: printable(typeof verification_uri_complete === "string" ? verification_uri_complete : verification_uri),
+    expiresInMs: expires_in * 1000,
+    intervalMs: (typeof interval === "number" && interval > 0 ? interval : 5) * 1000,
+  };
+}
+
+/** `<host> (eris)`, or `<host> (eris, claude-code)` under Claude Code: the
+ *  name the minted token carries in the dashboard's token list. */
+function deviceLabel(host: string, env: Record<string, string | undefined>): string {
+  const short = host.split(".")[0] || "unknown-host";
+  const harness = env.CLAUDECODE === "1" ? ", claude-code" : "";
+  return `${short} (eris${harness})`.slice(0, MAX_LABEL);
+}
+
+async function defaultOpenBrowser(url: string): Promise<void> {
+  if (!process.stderr.isTTY) return;
+  const cmd = process.platform === "darwin" ? ["open", url] : process.platform === "linux" ? ["xdg-open", url] : null;
+  if (cmd !== null) await runBounded(cmd, process.cwd(), 5_000);
+}
+
+function fail(ctx: VerbContext, slug: LoginSlug | "yak-config-permissive" | "yak-config-malformed" | "yak-config-unwritable", what: string, fix: string): number {
+  ctx.stderr.write(renderFailureBlock({ slug, what, fix }, ctx.erisDir));
+  return 1;
+}
+
+export async function runLogin(args: string[], ctx: VerbContext, deps: LoginDeps = {}): Promise<number> {
+  const a = readArgs(plugin.rows, "login", args, ctx, { help: LOGIN_USAGE });
+  if (a === null) return 0;
+  const home = deps.home ?? ctx.env.HOME ?? "";
+  const now = deps.now ?? Date.now;
+  const sleep = deps.sleep ?? ((ms: number) => Bun.sleep(ms));
+  const openBrowser = deps.openBrowser ?? defaultOpenBrowser;
+
+  const file = await readYaksFileConfig(home);
+  if ("reason" in file) return fail(ctx, file.slug, file.reason, `fix or remove ${yaksConfigPath(home)}, then run 'eris login' again`);
+
+  const url = resolveUrl(file.value, ctx.env, a.flags["--url"]).value;
+  const base = url.replace(/\/+$/, "");
+
+  // --- start -------------------------------------------------------------------
+  const started = await post(`${base}${DEVICE_AUTHORIZATION_PATH}`, { device: deviceLabel((deps.hostname ?? osHostname)(), ctx.env) });
+  if (started.kind === "unreachable") {
+    return fail(ctx, "login-unreachable", `cannot reach ${printable(base)}: ${started.reason}`, "check the url and your connection, then run 'eris login' again");
+  }
+  const grant = started.status === 200 ? readGrant(started.body) : null;
+  if (grant === null) {
+    const why = started.status === 200 ? "a malformed device authorization response" : errorCode(started.status, started.body);
+    return fail(ctx, "login-refused", `${printable(base)} refused to start a device login (${why})`, "check the url points at an endpoint with device login, then run 'eris login' again");
+  }
+
+  const opens = !a.flags["--no-browser"] && /^https?:\/\//i.test(grant.verificationUri);
+  ctx.stderr.write(
+    `To sign this machine in, open:\n\n  ${grant.verificationUri}\n\nand check it shows the code: ${grant.userCode}\n` +
+      `Waiting for approval (the code expires in ${Math.round(grant.expiresInMs / 60_000)} min)...\n`,
+  );
+  if (opens) await openBrowser(grant.verificationUri).catch(() => undefined);
+
+  // --- poll --------------------------------------------------------------------
+  const deadline = now() + grant.expiresInMs;
+  let interval = grant.intervalMs;
+  let wait = interval;
+  let transient = 0;
+  for (;;) {
+    await sleep(wait);
+    wait = interval;
+    if (now() >= deadline) {
+      return fail(ctx, "login-expired", "the device code expired before it was approved", "run 'eris login' again and approve the new code within its lifetime");
+    }
+    const polled = await post(`${base}${DEVICE_TOKEN_PATH}`, { grant_type: DEVICE_CODE_GRANT_TYPE, device_code: grant.deviceCode });
+
+    if (polled.kind === "unreachable" || polled.status >= 500) {
+      if (++transient > MAX_TRANSIENT) {
+        const why = polled.kind === "unreachable" ? polled.reason : errorCode(polled.status, polled.body);
+        return fail(ctx, "login-unreachable", `lost ${printable(base)} while waiting for approval (${why})`, "run 'eris login' again");
+      }
+      continue;
+    }
+    transient = 0;
+
+    if (polled.status === 429) {
+      const retryAfter = Number(polled.headers.get("retry-after"));
+      if (Number.isFinite(retryAfter) && retryAfter * 1000 > wait) wait = retryAfter * 1000;
+      continue;
+    }
+
+    if (polled.status === 200) {
+      const body = polled.body as Record<string, unknown> | null;
+      const token = body?.access_token;
+      if (typeof token !== "string" || token === "" || String(body?.token_type).toLowerCase() !== "bearer") {
+        return fail(ctx, "login-refused", "the endpoint approved the code but sent no bearer token", "run 'eris login' again");
+      }
+      const written = await writeYaksFileConfig({ url, token }, home);
+      if ("reason" in written) return fail(ctx, written.slug, written.reason, `make ${yaksConfigPath(home)} writable, then run 'eris login' again`);
+      if (file.value.token !== undefined && file.value.token !== token) {
+        ctx.stderr.write("replaced the token that was in the file; revoke it under Settings > API Tokens if nothing else uses it\n");
+      }
+      if (ctx.env.ERIS_YAKS_TOKEN) {
+        ctx.stderr.write(renderWarnLines("ERIS_YAKS_TOKEN is set and overrides the token just written; unset it to use this login", "login-env-token-overrides"));
+      }
+      const name = typeof body?.name === "string" ? printable(body.name) : "eris";
+      ctx.stdout.write(`logged in: token "${name}" written to ${written.value}\n`);
+      return 0;
+    }
+
+    const code = errorCode(polled.status, polled.body);
+    if (code === "authorization_pending") continue;
+    if (code === "slow_down") {
+      const raised = (polled.body as Record<string, unknown>).interval;
+      interval = typeof raised === "number" && raised * 1000 > interval ? raised * 1000 : interval + SLOW_DOWN_STEP_MS;
+      wait = interval;
+      continue;
+    }
+    if (code === "access_denied") {
+      return fail(ctx, "login-denied", "the sign-in was denied in the browser", "run 'eris login' again if that was not intended");
+    }
+    if (code === "expired_token") {
+      return fail(ctx, "login-expired", "the device code expired before it was approved", "run 'eris login' again and approve the new code within its lifetime");
+    }
+    return fail(ctx, "login-refused", `the endpoint refused the device code (${code})`, "run 'eris login' again");
+  }
+}
+
+export async function runLogout(args: string[], ctx: VerbContext, deps: Pick<LoginDeps, "home"> = {}): Promise<number> {
+  const a = readArgs(plugin.rows, "logout", args, ctx, { help: LOGOUT_USAGE });
+  if (a === null) return 0;
+  const home = deps.home ?? ctx.env.HOME ?? "";
+  const path = yaksConfigPath(home);
+
+  const file = await readYaksFileConfig(home);
+  if ("reason" in file) return fail(ctx, file.slug, file.reason, `fix or remove ${path}`);
+
+  if (file.value.token === undefined) {
+    ctx.stdout.write(`not logged in: no token in ${path}\n`);
+  } else {
+    if (file.value.url === undefined) {
+      try {
+        await fs.rm(path, { force: true });
+      } catch (err) {
+        return fail(ctx, "yak-config-unwritable", `cannot remove ${path}: ${(err as NodeJS.ErrnoException).code ?? "error"}`, `remove ${path} by hand`);
+      }
+    } else {
+      const written = await writeYaksFileConfig({ url: file.value.url }, home);
+      if ("reason" in written) return fail(ctx, written.slug, written.reason, `make ${path} writable, then run 'eris logout' again`);
+    }
+    ctx.stdout.write(`logged out: removed the token from ${path}\n`);
+    ctx.stderr.write("the token stays valid until it is revoked under Settings > API Tokens\n");
+  }
+  if (ctx.env.ERIS_YAKS_TOKEN) {
+    ctx.stderr.write(renderWarnLines("ERIS_YAKS_TOKEN is still set, so 'eris yak' keeps authenticating with it", "login-env-token-overrides"));
+  }
+  return 0;
+}

package/plugins/yak/yak-context.ts

@@ -0,0 +1,280 @@
+/**
+ * yak-context.ts — best-effort provenance gather for `eris yak`.
+ *
+ * Produces a `YakProvenance` record (`@sibylline-labs/yak-contract`) — six
+ * optional categories, each a permissive record:
+ * `execution`, `harness`, `device`, `process`, `repo`, `git`. NEVER a gate,
+ * NEVER a delay a caller should notice: every individual probe is wrapped so
+ * one failure drops exactly that key, and the WHOLE gather is time-capped so
+ * a slow filesystem or a hung `git` cannot make `eris yak` itself hang.
+ *
+ * Explicitly OUT of this module, because a provenance probe must never spawn
+ * work it cannot bound or reap, or prompt the user:
+ *
+ *   - no cloud CLI, no keychain read
+ *   - no config merge (no root/leaf deep-merge, excludes or overrides) —
+ *     `repo.service` below is a raw single-file peek at the nearest
+ *     `eris.yaml`
+ *   - no unbounded fan-out — exactly five bounded, individually-reaped `git`
+ *     subprocesses (`gatherGit`), run in parallel, each capped at
+ *     `GIT_PROBE_TIMEOUT_MS`
+ *
+ * `provenance` is redacted too: an origin URL can carry a token. That
+ * redaction pass is `plugins/yak/yak-redact.ts`, applied by the submission
+ * core (`yak-submit.ts`), which is where the whole payload — `summary`, `body`,
+ * `evidence`, AND this provenance record — gets one redaction pass before
+ * key derivation. This module only gathers; it does not redact.
+ */
+
+import { promises as fs } from "node:fs";
+import { dirname, join } from "node:path";
+import { hostname } from "node:os";
+import type { YakProvenance } from "eris/yak-contract";
+import { asText, runBounded, type Runner } from "./yak-identity";
+
+const GIT_PROBE_TIMEOUT_MS = 500;
+/** Overall wall-clock budget for the whole gather. Generous headroom over
+ *  the five GIT_PROBE_TIMEOUT_MS probes (which run in PARALLEL, so their
+ *  worst case is ~one timeout, not five) plus the synchronous/fs-only
+ *  categories, while still being "an agent won't notice this" fast for a
+ *  mid-task CLI call. If this fires, every category still in flight is
+ *  simply omitted — never awaited to completion, never thrown. */
+const OVERALL_GATHER_TIMEOUT_MS = 1_500;
+/** Filesystem-root backstop for the `repo.service` walk-up. A real checkout
+ *  never nests this deep; this exists so a symlink cycle or an unexpectedly
+ *  deep tree can't turn a "cheap peek" into an unbounded walk. */
+const REPO_WALK_MAX_DEPTH = 64;
+
+export type ProvenanceOptions = {
+  env?: Record<string, string | undefined>;
+  cwd?: string;
+  pid?: number;
+  ppid?: number;
+  run?: Runner;
+};
+
+/**
+ * Gather best-effort provenance. Never throws, never exceeds
+ * `OVERALL_GATHER_TIMEOUT_MS` in wall time regardless of how slow any single
+ * probe is, and every category it returns has at least one key (an empty
+ * category is omitted rather than emitted as `{}`: absent means nothing was
+ * measured, so an empty object would claim a measurement that never happened).
+ */
+export async function gatherProvenance(opts: ProvenanceOptions = {}): Promise<YakProvenance> {
+  const env = opts.env ?? process.env;
+  const cwd = opts.cwd ?? process.cwd();
+  const pid = opts.pid ?? process.pid;
+  const ppid = opts.ppid ?? process.ppid;
+  const run = opts.run ?? runBounded;
+
+  const provenance: YakProvenance = {};
+
+  const categories: Array<[keyof YakProvenance, Promise<Record<string, unknown> | undefined>]> = [
+    ["execution", Promise.resolve(safeRecord(() => gatherExecution(env)))],
+    ["harness", Promise.resolve(safeRecord(() => gatherHarness(env)))],
+    ["device", Promise.resolve(safeRecord(() => gatherDevice()))],
+    ["process", Promise.resolve(safeRecord(() => gatherProcess(env, cwd, pid, ppid)))],
+    ["repo", safeRecordAsync(() => gatherRepo(cwd))],
+    ["git", safeRecordAsync(() => gatherGit(cwd, run))],
+  ];
+
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const deadline = new Promise<void>((resolve) => {
+    timer = setTimeout(resolve, OVERALL_GATHER_TIMEOUT_MS);
+  });
+
+  try {
+    await Promise.race([
+      Promise.allSettled(
+        categories.map(([key, p]) =>
+          p.then((rec) => {
+            if (rec !== undefined) provenance[key] = rec;
+          }),
+        ),
+      ),
+      deadline,
+    ]);
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+  }
+
+  return provenance;
+}
+
+// --- per-field helpers --------------------------------------------------------
+
+/** Set `rec[key]` only when `producer()` returns a defined value; a thrown
+ *  error or an `undefined` return drops exactly this ONE field and nothing
+ *  else in the record. */
+function trySet<T>(rec: Record<string, unknown>, key: string, producer: () => T | undefined): void {
+  try {
+    const value = producer();
+    if (value !== undefined) rec[key] = value;
+  } catch {
+    // this field drops; every other field in the same record is unaffected
+  }
+}
+
+function nonEmpty(value: string | undefined): string | undefined {
+  return value && value.length > 0 ? value : undefined;
+}
+
+/** Wrap a whole category producer: catch anything it throws, and treat a
+ *  zero-key result as ABSENT (omit the category) rather than emitting `{}` —
+ *  a category nobody could speak to is different from a category that spoke
+ *  and said nothing, and only the record's own fields (via `trySet`) can
+ *  legitimately be empty of content. */
+function safeRecord(producer: () => Record<string, unknown>): Record<string, unknown> | undefined {
+  try {
+    const rec = producer();
+    return Object.keys(rec).length > 0 ? rec : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+async function safeRecordAsync(
+  producer: () => Promise<Record<string, unknown>>,
+): Promise<Record<string, unknown> | undefined> {
+  try {
+    const rec = await producer();
+    return Object.keys(rec).length > 0 ? rec : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+// --- execution / harness / device / process (sync, no I/O) ------------------
+
+/** Session identity — what task this yak belongs to, mirroring the
+ *  `resolveExecutionId` ladder's own rungs (`yak-identity.ts`) as raw facts
+ *  rather than the one resolved value, so a reader can see which rungs were
+ *  actually populated in this process's environment. */
+function gatherExecution(env: Record<string, string | undefined>): Record<string, unknown> {
+  const rec: Record<string, unknown> = {};
+  trySet(rec, "claude_code_session_id", () => nonEmpty(env.CLAUDE_CODE_SESSION_ID));
+  trySet(rec, "claude_code_host_session_id", () => nonEmpty(env.CLAUDE_CODE_HOST_SESSION_ID));
+  trySet(rec, "entrypoint", () => nonEmpty(env.CLAUDE_CODE_ENTRYPOINT));
+  return rec;
+}
+
+/** Which harness is running, and what version of it — the three env vars
+ *  actually OBSERVED set in a live Claude Code session (`CLAUDECODE=1`,
+ *  `AI_AGENT=claude-code_2-1-222_agent`, `CLAUDE_AGENT_SDK_VERSION=0.3.222`),
+ *  not a guessed name. `AI_AGENT`'s value already embeds a version-shaped
+ *  string; `CLAUDE_AGENT_SDK_VERSION` is a second, more literal version
+ *  fact when the harness sets it. */
+function gatherHarness(env: Record<string, string | undefined>): Record<string, unknown> {
+  const rec: Record<string, unknown> = {};
+  trySet(rec, "claudecode", () => nonEmpty(env.CLAUDECODE));
+  trySet(rec, "ai_agent", () => nonEmpty(env.AI_AGENT));
+  trySet(rec, "claude_agent_sdk_version", () => nonEmpty(env.CLAUDE_AGENT_SDK_VERSION));
+  return rec;
+}
+
+function gatherDevice(): Record<string, unknown> {
+  const rec: Record<string, unknown> = {};
+  trySet(rec, "hostname", () => nonEmpty(hostname()));
+  trySet(rec, "platform", () => nonEmpty(process.platform));
+  trySet(rec, "arch", () => nonEmpty(process.arch));
+  return rec;
+}
+
+function gatherProcess(
+  env: Record<string, string | undefined>,
+  cwd: string,
+  pid: number,
+  ppid: number,
+): Record<string, unknown> {
+  const rec: Record<string, unknown> = {};
+  trySet(rec, "cwd", () => nonEmpty(cwd));
+  trySet(rec, "pid", () => pid);
+  trySet(rec, "ppid", () => ppid);
+  trySet(rec, "shell", () => nonEmpty(env.SHELL));
+  return rec;
+}
+
+// --- repo (a raw single-file peek, never a config merge) -------------------
+
+async function gatherRepo(cwd: string): Promise<Record<string, unknown>> {
+  const rec: Record<string, unknown> = {};
+  const service = await findNearestErisYamlService(cwd);
+  if (service !== undefined) rec.service = service;
+  return rec;
+}
+
+/**
+ * Walk up from `startDir` looking for the nearest `eris.yaml` and read its
+ * top-level `service:` field directly — no root/leaf merge, no
+ * excludes/overrides. Bounded two ways: a hard iteration ceiling
+ * (`REPO_WALK_MAX_DEPTH`) and stopping at the enclosing git checkout's root
+ * (a `.git` entry, file or directory), so this cheap peek never wanders into
+ * a sibling repo above the one it was invoked from.
+ */
+async function findNearestErisYamlService(startDir: string): Promise<string | undefined> {
+  let dir = startDir;
+  for (let i = 0; i < REPO_WALK_MAX_DEPTH; i++) {
+    const candidate = join(dir, "eris.yaml");
+    try {
+      const raw = await fs.readFile(candidate, "utf8");
+      const parsed = Bun.YAML.parse(raw);
+      if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+        const service = (parsed as Record<string, unknown>).service;
+        if (typeof service === "string" && service.length > 0) return service;
+      }
+      // A manifest exists here but has no usable `service:` — it is still
+      // the NEAREST one, so stop rather than walking past it.
+      return undefined;
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "ENOENT") return undefined; // unreadable — drop, never throw
+    }
+
+    if (await isGitCheckoutRoot(dir)) return undefined; // reached the repo root with no manifest
+
+    const parent = dirname(dir);
+    if (parent === dir) return undefined; // filesystem root
+    dir = parent;
+  }
+  return undefined;
+}
+
+async function isGitCheckoutRoot(dir: string): Promise<boolean> {
+  try {
+    await fs.access(join(dir, ".git"));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// --- git (five bounded, individually-reaped subprocesses) -------------------
+
+async function gatherGit(cwd: string, run: Runner): Promise<Record<string, unknown>> {
+  const rec: Record<string, unknown> = {};
+
+  const [root, origin, branch, sha, status] = await Promise.all([
+    run(["git", "rev-parse", "--show-toplevel"], cwd, GIT_PROBE_TIMEOUT_MS),
+    run(["git", "config", "--get", "remote.origin.url"], cwd, GIT_PROBE_TIMEOUT_MS),
+    run(["git", "rev-parse", "--abbrev-ref", "HEAD"], cwd, GIT_PROBE_TIMEOUT_MS),
+    run(["git", "rev-parse", "HEAD"], cwd, GIT_PROBE_TIMEOUT_MS),
+    run(["git", "status", "--porcelain"], cwd, GIT_PROBE_TIMEOUT_MS),
+  ]);
+
+  const rootText = asText(root);
+  if (rootText !== undefined) rec.root = rootText;
+  const originText = asText(origin);
+  if (originText !== undefined) rec.origin_url = originText;
+  const branchText = asText(branch);
+  if (branchText !== undefined) rec.branch = branchText;
+  const shaText = asText(sha);
+  if (shaText !== undefined) rec.head_sha = shaText;
+
+  // `dirty` is a BOOLEAN fact, not free text: absent only when the PROBE
+  // itself failed (no `git`, not a repo, timeout) — never when the tree is
+  // simply clean, which is a legitimate `false` produced by EMPTY stdout on
+  // exit 0. Routing this through `asText` (which treats empty as absent)
+  // would make a dirty tree indistinguishable from an unmeasured one.
+  if (status.ok) rec.dirty = status.stdout.trim().length > 0;
+
+  return rec;
+}