prismalens 0.4.0 → 0.5.0-rc.0

package/README.md

@@ -1,370 +1,44 @@
 # prismalens
 
-The PrismaLens **investigation engine CLI** — the `prismalens` (alias `pl`) binary,
-published on npm as the unscoped [`prismalens`](https://www.npmjs.com/package/prismalens) package.
-
-Per **ADR-0010**, the engine *is* a CLI: the desktop app and web API drive it
-rather than embedding it. The CLI is a thin **Tier-1 supervisor** that rents a
-**Tier-2 agent harness** (ADR-0008) to do the investigative legwork, then reduces the
-harness's canonical event stream into an **ordered-evidence report** (ADR-0002 —
-hypotheses ranked most-to-least plausible, with supporting/contradicting
-evidence; no numeric confidence scores).
-
-- **Tier-1 (supervisor):** seeds the investigation from a firing alert, drives the
-  rented harness live, and synthesizes the final report (the "reduce" step) using
-  an OpenAI-compatible model.
-- **Tier-2 (rented harness):** one of
-  - `deepagents` — driven over **ACP**,
-  - `claude-code` — driven over the **Claude Agent SDK**,
-  - `codex` — **stubbed** (not implemented; selecting it throws).
-
-## How the harness is contained
-
-By default prismalens removes the harness's edit tools (`Edit`, `Write`,
-`MultiEdit`, `NotebookEdit`). That is a **guardrail, not a security boundary**
-(ADR-0017): the shell is untouched, so writes remain possible via `Bash`. It is
-there to stop a *helpful* agent from editing the repo it was asked to investigate
-— it will not stop a determined one.
-
-**Without a sandbox, the harness runs as you** — your machine, your credentials,
-your shell — exactly as if you had invoked the agent CLI yourself. prismalens
-makes no safety claim in this mode, and none of the above should be read as one.
-
-The **only** real boundary is an enforced sandbox (`--sandbox srt` or `e2b`,
-ADR-0020): an OS-level box in which your host and credentials are read-only, the
-harness gets a read-write **workspace**, and network egress is **allowlisted**.
-Note that this is *confined writes*, not "read-only" — an investigation has to be
-able to clone a repo and download artifacts. `--sandbox auto` is not yet an
-enforced default; it can degrade to an unenforced floor.
-
-Provider credentials are **BYO-key** (ADR-0006), resolved from the environment or
-the local auth store — never hard-bound in the CLI.
-
-Every run is persisted to a durable workspace under `~/.prismalens/runs/<runId>/`
-(`events.jsonl` + `report.json` + `session.json`), regardless of how it was
-invoked.
-
----
+PrismaLens is an AI-powered root-cause investigation tool for on-call engineers. It analyzes firing alerts against your repositories and telemetry, producing an ordered-evidence report that ranks hypotheses by observed evidence without synthetic confidence scores. The CLI runs standalone or boots the full local application.
 
 ## Install
 
-Requires Node.js >= 22.
+Requires Node.js 24+.
 
 ```bash
-# one-off, nothing installed globally
-npx prismalens doctor
-
-# or install the `prismalens` / `pl` bins globally
 npm install -g prismalens
 ```
 
-## Build from source
-
-This package lives in the pnpm + turbo monorepo and is consumed by the rest of the
-platform via `workspace:*`.
-
-```bash
-# from the repo root
-pnpm install
-
-# build the CLI and its workspace deps (@prismalens/contracts, @prismalens/engine)
-pnpm build                      # turbo build (whole monorepo)
-# or just this package + its deps:
-pnpm --filter prismalens... build
-```
-
-The build emits `dist/`, exposing two bin entries (identical):
+## Quick start
 
-```
-prismalens -> dist/bin/prismalens.js
-pl         -> dist/bin/prismalens.js
-```
-
-For local development you can skip the build and run the TypeScript entry directly:
+Check the environment, then start the web interface or run an investigation directly:
 
 ```bash
-# from packages/cli
-pnpm dev investigate --query "checkout latency spike"   # tsx bin/prismalens.ts ...
+prismalens doctor
+pl up
+pl investigate --repo . --query "checkout latency spike after 14:00 UTC"
 ```
 
-Run `prismalens doctor` before your first investigation to verify the harness
-binary and an LLM credential are present.
-
----
-
 ## Commands
 
-```
-prismalens <command> [flags]      # alias: pl
-
-  investigate   Run a read-only root-cause investigation of a firing alert.
-  listen        Start a token-authed local HTTP listener for Alertmanager webhooks.
-  serve         Run the JSON-RPC 2.0 server over stdio (the LIVE channel for apps).
-  doctor        Preflight-check the investigation environment.
-  init          Scaffold a prismalens.config.yaml in the current directory.
-  auth          Manage stored BYO-key credentials for providers.
-```
-
-### `investigate`
-
-Seeds an investigation from a firing alert, rents a Tier-2 harness, streams the
-supervisor live (each canonical event is appended to the run workspace and printed
-as a one-line timeline entry), and renders the ordered-evidence report.
-
-The seed alert comes from **one of**:
-- a **`FiringAlert` JSON piped on stdin** (also accepts a webhook/Alertmanager-shaped
-  payload — `alertname`/`severity` are pulled from top-level fields, falling back to
-  `labels`), or
-- `--query` — a one-line description that is synthesized into a minimal alert.
-
-| Flag | Description |
-| --- | --- |
-| `--repo <dir>` | Path to the repository the harness investigates (its cwd). Defaults to the current directory. |
-| `--query, -q <text>` | Synthesize an alert from this one-line description (alternative to piping a `FiringAlert` JSON on stdin). |
-| `--config <path>` | Path to a `prismalens.config.yaml` (skips the upward config search; fails closed for missing, unreadable, or invalid paths). |
-| `--model <id>` | Override `agent.model` — a bare model id, e.g. `gpt-oss:120b`. |
-| `--max-turns <n>` | Per-run turn ceiling for the default harness. |
-| `--harness <name>` | Tier-2 backend: `deepagents` \| `claude-code` \| `codex`. Defaults to `agent.default`. |
-| `--json` | Print the `InvestigationReport` as JSON to stdout (suppresses the human renderer; implies quiet). |
-| `--output <file>` | Also write the `InvestigationReport` JSON to this file. |
-| `--quiet` | Suppress progress + the human renderer (errors still go to stderr). |
-
-**Exit codes:** `0` on a synthesized report; `1` on a hard input error, a
-mid-stream failure, or a **no-evidence** run (a branch that gathered nothing and
-errored emits no report — the CLI surfaces the transport failure rather than a
-fabricated RCA).
-
-A `FiringAlert` is `{ alertname, severity, labels, annotations, startsAt }`.
-
-### `listen`
-
-Start a token-authed local HTTP listener for Alertmanager webhooks; each firing alert triggers an investigation (Phase 1 R1).
-
-```bash
-PRISMALENS_LISTEN_TOKEN=xyz pl listen --config my-stack.yaml
-```
-
-### `serve`
-
-Runs the JSON-RPC 2.0 server over stdio — the live channel apps drive (see
-[Driven by an app](#mode-2--driven-by-an-app-prismalens-serve)). No flags.
-
-### `doctor`
-
-Preflight checklist that gates a run. Prints pass/fail per check; exits non-zero
-**iff a hard check fails**.
-
-- **HARD — harness binary on PATH:** `deepagents` → `deepagents-acp`,
-  `claude-code` → `claude`, `codex` → `codex` (for the harness from config).
-- **HARD — an LLM credential:** any of `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` /
-  `GOOGLE_API_KEY` / `OLLAMA_API_KEY` / `GROQ_API_KEY` / `CUSTOM_LLM_API_KEY`,
-  a credential stored via `pl auth login` (`auth.json`), or, for `claude-code`,
-  a signed-in `~/.claude/.credentials.json`. Doctor reports which layer supplied
-  the credential (`source: env | file | stored | none`). (Performs a live
-  provider model ping by default, while `--no-ping` skips it.)
-- **SOFT — workspace writable:** `workspace.dir` can be created/written.
-
-### `init`
-
-Scaffolds a commented `prismalens.config.yaml` in the current directory, sourced
-from the schema defaults so it never drifts from what the engine uses.
-Non-interactive: if the file already exists it is left untouched.
-
----
-
-## Usage modes
-
-### Mode 1 — standalone
-
-Run an investigation straight from the terminal. Inputs are resolved from the cwd
-(or `--repo`), stdin/`--query`, and the merged config; the report is rendered to
-the terminal and written to `~/.prismalens/runs/<runId>/`.
-
-```bash
-# Synthesized alert from a one-liner, deepagents harness, investigating ./my-service
-prismalens investigate \
-  --repo ./my-service \
-  --query "p99 checkout latency tripled after 14:00 UTC" \
-  --harness deepagents
-
-# Pipe a real FiringAlert (or webhook/Alertmanager-shaped) payload on stdin
-cat alert.json | prismalens investigate --repo ./my-service
-
-# Machine-readable report (JSON to stdout) + a copy on disk, no progress chatter
-prismalens investigate -q "OOMKilled in payments pod" --json --output report.json
-
-# Pull the currently-firing alert from Alertmanager and investigate it
-curl -s http://localhost:9093/api/v2/alerts?active=true \
-  | jq '.[0]' \
-  | prismalens investigate --repo ./payments --harness claude-code
-```
-
-Durable record for every run:
-
-```
-~/.prismalens/
-  sessions.json                  # run index (runId -> SessionRecord)
-  runs/<runId>/session.json      # per-run metadata mirror
-  runs/<runId>/events.jsonl      # canonical event stream (one JSON per line)
-  runs/<runId>/report.json       # the synthesized InvestigationReport
-```
-
-### Mode 2 — driven by an app (`prismalens serve`)
-
-This is the **live channel** for the desktop app and web API — it replaces the old
-`pl` file-watching reporter. The engine streams via `investigateIncidentStream`
-(an async generator); `serve` forwards each canonical event as a notification.
-Validated live against the sreforge `booklogr` incident with **both** harnesses
-(`deepagents` over ACP, `claude-code` over the Agent SDK). The
-`~/.prismalens/runs/<runId>/` workspace remains the durable record.
-
-**Protocol:** JSON-RPC 2.0 over **stdio**, **newline-delimited** (one JSON value
-per line in both directions — requests on stdin; responses + notifications on
-stdout).
-
-**`initialize`**
-
-```jsonc
---> {"jsonrpc":"2.0","id":1,"method":"initialize"}
-<-- {"jsonrpc":"2.0","id":1,"result":{
-      "protocolVersion": 1,
-      "serverInfo": { "name": "prismalens", "version": "0.0.1" }
-    }}
-```
-
-**`investigate`** — `params`: `{ alert?: FiringAlert, query?: string, repo?: string,
-harness?: string, model?: string, config?: string, service?: string, mode?: string,
-dangerouslySkipPermissions?: boolean, sandbox?: string, maxTurns?: number }`.
-
-CLI-parity params (each falls back to config when absent):
-
-- `sandbox` — the isolation boundary (ADR-0020), the CLI's `--sandbox`: one of
-  `auto` | `process` | `srt` | `e2b`. Absent ⇒ `agent.sandbox` from config. A
-  supplied value that is not a known mode (or a mode the resolved harness cannot
-  honour, e.g. `srt` on a non-ACP harness) is a `-32602` error — never a silent
-  fall-back to the cooperative floor.
-- `maxTurns` — per-run turn ceiling, the CLI's `--max-turns`: a positive integer.
-  A supplied zero, negative, fractional, or non-numeric value is a `-32602` error —
-  never a silently-removed cap.
-
-Streams a **notification per canonical event** (including the terminal `report`
-event), then **resolves the request** with `{ runId, report }`:
-
-```jsonc
---> {"jsonrpc":"2.0","id":2,"method":"investigate",
-     "params":{"query":"checkout latency spike","repo":"./my-service","harness":"deepagents"}}
-
-// zero or more notifications, in order, as the supervisor streams:
-<-- {"jsonrpc":"2.0","method":"investigate/event",
-     "params":{"runId":"<uuid>","event":{ /* CanonicalEvent */ }}}
-// ... agent_step, tool_result, branch_done, (error), then the terminal report event ...
-
-// finally, the request resolves:
-<-- {"jsonrpc":"2.0","id":2,"result":{"runId":"<uuid>","report":{ /* InvestigationReport */ }}}
-```
-
-`CanonicalEvent.kind` is one of `agent_step` | `tool_result` | `branch_done` |
-`error` | `report`. Requests are fire-and-forget on the wire: multiple may run
-concurrently and interleave their notifications — each notification carries its
-`runId` so a driver can demultiplex.
-
-**Error codes:**
-
-| Code | Meaning |
+| Command | Description |
 | --- | --- |
-| `-32700` | Parse error (invalid JSON on a line). |
-| `-32600` | Invalid request (not a well-formed JSON-RPC 2.0 request). |
-| `-32601` | Method not found. |
-| `-32602` | Invalid params (includes an invalid `sandbox` mode or `maxTurns` value, and `resolveInvestigation` input errors — e.g. no alert/query, unknown or unbuilt harness). |
-| `-32603` | Internal error (mid-stream failure; `data` carries `{ runId }`). |
-| `-32000` | No evidence — the harness branch failed and produced no report (`data` carries `{ runId }`). |
-
-A malformed or failed request becomes a JSON-RPC error response — the server never
-crashes on bad input.
-
----
-
-## Configuration
-
-`prismalens.config.yaml` (run `prismalens init` to scaffold one). Resolution order,
-later overriding earlier:
-
-1. built-in schema defaults,
-2. user layer — `config.yaml` in the OS config dir (Linux/WSL:
-   `~/.config/prismalens/config.yaml`; macOS/Windows use the platform config dir),
-   a good home for BYO-key creds via `${VAR}` interpolation,
-3. project layer — the explicit `--config` path, else the nearest config file found
-   by walking **up** from the cwd,
-4. CLI flag overrides (e.g. `--model`).
-
-`${VAR}` patterns in string values are interpolated from the environment (an unset
-var is an error).
-
-```yaml
-# Tier-2 harness backend the supervisor rents (ADR-0008).
-agent:
-  default: deepagents            # deepagents | claude-code | codex
-  # model: gpt-oss:120b          # bare id — the harness applies its own provider
-                                 # prefix; omit to let the harness default
-  sandbox: auto                  # auto | process | srt — isolation boundary (ADR-0020).
-                                 # auto (default): srt (enforced OS boundary) WHEN its
-                                 # egress bridge is healthy (a self-check catches WSL
-                                 # mirrored-networking blackouts), else the cooperative
-                                 # process floor — the degrade is logged, never silent.
-
-# Read-only telemetry + app endpoints the harness may query.
-telemetry:
-  prometheus_url: http://localhost:9090
-  alertmanager_url: http://localhost:9093
-  api_url: http://localhost:3000
-
-# Where runs, events, and reports are stored.
-workspace:
-  dir: ~/.prismalens
-
-# Per-harness native passthrough (ADR-0017) — untyped, forwarded straight to the
-# rented harness. For `deepagents` (the npm `deepagents-acp` binary, driven over
-# ACP), `args` is appended verbatim to the CLI invocation. The binary has no
-# shell-allowlist or sandbox flags — so the harness is unsandboxed (runs as you)
-# until the Sandbox port's enforced providers land (ADR-0020/B.1).
-harnesses:
-  deepagents:
-    native:
-      args: [--memory, ./AGENTS.md]
-```
-
-Notes:
-- `agent.model` sets the **Tier-2 harness** model only (a bare id, e.g. `gpt-oss:120b`;
-  each harness applies its own provider prefix). `--model` overrides it.
-- `synth.model` sets the **Tier-1 reduce** (report-synthesis) model — a separate call
-  to a separate provider (ADR-0013/0016). `agent.model` never feeds it, so a harness on
-  one provider (e.g. `claude-code`) can't misroute the reduce call to another (ollama).
-- `telemetry.*` keys are snake_case (`prometheus_url`, `alertmanager_url`, `api_url`)
-  and default to host-local URLs when unset.
-- There is currently no `agent.timeout_ms`, `budget.*`, or `logging.*` config —
-  an overall per-run wall-clock budget and a Tier-1 reduce token/retry budget are
-  planned alongside the Phase B.1 Sandbox port's resource limits (ADR-0020), not
-  wired yet.
-
-### BYO-key environment (ADR-0006)
-
-Credentials are BYO-key and never hard-bound in the CLI. They can be read from the environment or stored locally via the `auth` command.
+| `up` | Run PrismaLens as a single process serving the API and web dashboard. |
+| `investigate` | Run a root-cause investigation on a firing alert or query. |
+| `listen` | Start a local HTTP webhook receiver for incoming Alertmanager alerts. |
+| `serve` | Run the JSON-RPC server over stdio for desktop and API integrations. |
+| `doctor` | Preflight-check the environment for harness binaries and credentials. |
+| `init` | Scaffold a default configuration file in the current directory. |
+| `status` | List recent investigation runs and their execution states. |
+| `report` | Display the stored investigation report for a specific run ID. |
+| `auth` | Manage stored credentials for model providers. |
 
-The resolution precedence for any credential is: **env** (`PROVIDER_API_KEY`) → **_FILE** (`PROVIDER_API_KEY_FILE`) → **stored** (from `auth.json`) → **none**.
+## Documentation
 
-**Auth commands:**
-- `pl auth login <provider> [--api-key <key>]` — save a credential (prompts securely if `--api-key` is omitted).
-- `pl auth list` — view saved providers.
-- `pl auth logout <provider>` — remove a saved credential.
+Complete documentation, guides, and configuration references are available at https://docs.prismalens.io.
 
-Stored credentials live in `auth.json` inside the app-data dir (`~/.prismalens` by default, honors `PRISMALENS_WORKSPACE_DIR`), enforced to mode `0600`.
+## License
 
-- **Tier-1 reduce + the `deepagents` harness** use an OpenAI-compatible endpoint:
-  - `OLLAMA_API_KEY` or `OPENAI_API_KEY` (the API key),
-  - `OLLAMA_BASE_URL` or `OPENAI_BASE_URL` (base URL; defaults to
-    `https://ollama.com/v1`).
-- **The `claude-code` harness** uses your signed-in `~/.claude` session, or
-  `ANTHROPIC_API_KEY`.
+Apache-2.0
 
-If no matching credential is found across the resolution chain, the reduce (synthesis) call will
-likely fail — `investigate` warns up front, and `doctor` checks for a credential.

package/dist/bin/prismalens.js

@@ -25,6 +25,7 @@ var main = defineCommand({
     description: "PrismaLens investigation engine CLI \u2014 drives the two-tier engine (ADR-0008/0010)."
   },
   subCommands: {
+    up: lazy("up"),
     investigate: lazy("investigate"),
     listen: lazy("listen"),
     serve: lazy("serve"),

package/dist/{chunk-TGP6QTFO.js → chunk-5STPIUCJ.js}

@@ -1,13 +1,7 @@
-import {
-  HARNESS_IDS,
-  PERMISSION_MODES,
-  SANDBOX_MODES
-} from "./chunk-5BT3XQOG.js";
-import {
-  llmProviderIdSchema
-} from "./chunk-XH6DIKTA.js";
-
 // src/config/schema.ts
+import { HARNESS_IDS, PERMISSION_MODES } from "@prismalens/config/harness";
+import { llmProviderIdSchema } from "@prismalens/config/llm";
+import { SANDBOX_MODES } from "@prismalens/engine";
 import { z } from "zod";
 var PermissionConfigSchema = z.object({
   mode: z.enum(PERMISSION_MODES).default("read-only")
@@ -117,7 +111,7 @@ function optionalWithDefaults(schema) {
     const res = schema.safeParse(val ?? {});
     if (!res.success) {
       for (const issue of res.error.issues) {
-        ctx.addIssue(issue);
+        ctx.addIssue({ ...issue });
       }
       return z.NEVER;
     }

package/dist/{chunk-PVQVFRIV.js → chunk-JX2QAP6S.js}

@@ -1,51 +1,31 @@
 import {
   loadConfig
-} from "./chunk-V6M6ISKI.js";
+} from "./chunk-VI32U36Y.js";
 import {
   createSessionManager
-} from "./chunk-CTKCK7QT.js";
-import {
-  resolveInvestigation
-} from "./chunk-QDK5PAI3.js";
+} from "./chunk-TSW5RW5B.js";
 import {
   assertKnownFlags
 } from "./chunk-PTBCAI34.js";
-import {
-  HARNESS_REGISTRY,
-  SANDBOX_MODES,
-  conductRun,
-  resolveSandbox
-} from "./chunk-5BT3XQOG.js";
-import {
-  INVESTIGATION_DEFAULTS
-} from "./chunk-6N4PHBII.js";
 
 // src/cli/investigate.ts
 import { randomUUID } from "node:crypto";
 import { writeFile } from "node:fs/promises";
-import { join, resolve } from "node:path";
+import { join, resolve as resolve2 } from "node:path";
+import { HARNESS_REGISTRY } from "@prismalens/config/harness";
+import { INVESTIGATION_DEFAULTS as INVESTIGATION_DEFAULTS2 } from "@prismalens/config/investigation";
+import {
+  conductRun,
+  resolveSandbox,
+  SANDBOX_MODES
+} from "@prismalens/engine";
 import { defineCommand } from "citty";
 import consola from "consola";
 
 // src/core/detect-repo.ts
-import { execFile } from "node:child_process";
-import { promisify } from "node:util";
-var execFileAsync = promisify(execFile);
-var REPO_PATTERN = /(?:github\.com|gitlab\.com|bitbucket\.org)[/:](.+?)(?:\.git)?$/;
-async function detectRepo(cwd) {
-  try {
-    const { stdout } = await execFileAsync(
-      "git",
-      ["remote", "get-url", "origin"],
-      { cwd }
-    );
-    return stdout.trim().match(REPO_PATTERN)?.[1];
-  } catch {
-    return void 0;
-  }
-}
+import { detectRepoSlug } from "@prismalens/config";
 async function resolveRepoSlug(configRepo, cwd = process.cwd()) {
-  return configRepo ?? await detectRepo(cwd);
+  return configRepo ?? await detectRepoSlug(cwd);
 }
 
 // src/core/file-session-store.ts
@@ -99,6 +79,146 @@ async function parseStdin() {
   }
 }
 
+// src/core/run-investigation.ts
+import { resolve } from "node:path";
+import { pickServiceLabel } from "@prismalens/config";
+import { ensureV1, resolveCredentials } from "@prismalens/config/credentials";
+import { INVESTIGATION_DEFAULTS } from "@prismalens/config/investigation";
+import {
+  AUTO_SELECT_PROVIDER_IDS,
+  getDefaultModel
+} from "@prismalens/config/llm";
+import {
+  coerceFiringAlert,
+  resolveInvestigation as engineResolveInvestigation
+} from "@prismalens/engine";
+function isSynthConfigured(config) {
+  if (config.synth.provider) {
+    return resolveCredentials(config.synth.provider, config.synth.base_url).source !== "none";
+  }
+  for (const id of AUTO_SELECT_PROVIDER_IDS) {
+    if (resolveCredentials(id).source !== "none") {
+      return true;
+    }
+  }
+  return false;
+}
+function resolveInvestigation(args, config) {
+  const cwd = args.repo ? resolve(args.repo) : process.cwd();
+  let providerId = config.synth.provider;
+  let creds;
+  if (providerId) {
+    creds = resolveCredentials(providerId, config.synth.base_url);
+    if (providerId === "custom" && !creds.baseURL) {
+      throw new Error(
+        "Custom LLM provider requires synth.base_url to be configured."
+      );
+    }
+  } else {
+    for (const id of AUTO_SELECT_PROVIDER_IDS) {
+      const candidate = resolveCredentials(id);
+      if (candidate.source !== "none") {
+        providerId = id;
+        break;
+      }
+    }
+    if (providerId) {
+      creds = resolveCredentials(
+        providerId,
+        config.synth.base_url
+      );
+    } else {
+      creds = { providerId: "ollama", source: "none" };
+      providerId = "ollama";
+    }
+  }
+  const synthModel = config.synth.model ?? getDefaultModel(providerId) ?? "";
+  if (!synthModel && creds.source !== "none") {
+    throw new Error("No synthesis model configured (set synth.model).");
+  }
+  const service = selectService(args, config);
+  const repos = config.repo ? [config.repo] : Object.keys(config.repos).length > 0 ? Object.keys(config.repos) : void 0;
+  const logs = config.logs.url ? {
+    ...config.logs.kind ? { kind: config.logs.kind } : {},
+    url: config.logs.url
+  } : void 0;
+  const harnessName = args.harness ?? config.agent.default;
+  const permissionMode = args.permissionMode ?? config.agent.permissions.mode;
+  const harnessNative = config.harnesses[harnessName]?.native;
+  const limits = toSandboxLimits(config.agent.limits);
+  const telemetry = {
+    prometheusUrl: config.telemetry.prometheus_url ?? INVESTIGATION_DEFAULTS.telemetry.prometheusUrl,
+    alertmanagerUrl: config.telemetry.alertmanager_url ?? INVESTIGATION_DEFAULTS.telemetry.alertmanagerUrl,
+    apiUrl: config.telemetry.api_url ?? INVESTIGATION_DEFAULTS.telemetry.apiUrl
+  };
+  const request = {
+    query: args.query,
+    harness: harnessName,
+    permissionMode,
+    ...harnessNative ? { harnessNative } : {},
+    ...args.sandbox ? { sandbox: args.sandbox } : {},
+    ...args.requestedSandbox ? { requestedSandbox: args.requestedSandbox } : {},
+    ...limits ? { limits } : {},
+    // Per-alert fan-out cap (ADR-0016 decision 2): wire `agent.max_branches` when
+    // set; unset leaves the engine default (mirrors the `limits` thread-through).
+    ...config.agent.max_branches ? { maxBranches: config.agent.max_branches } : {},
+    ...args.maxTurns ? { maxTurns: args.maxTurns } : {},
+    ...args.isolateSettings ? { isolateSettings: args.isolateSettings } : {},
+    model: config.agent.model,
+    cwd,
+    synth: {
+      providerId,
+      model: synthModel,
+      apiKey: creds.apiKey ?? "",
+      baseURL: creds.baseURL,
+      configured: creds.source !== "none"
+    },
+    harnessEnv: {
+      OPENAI_API_KEY: process.env.OLLAMA_API_KEY ?? process.env.OPENAI_API_KEY,
+      OPENAI_BASE_URL: ensureV1(
+        process.env.OLLAMA_BASE_URL ?? process.env.OPENAI_BASE_URL ?? INVESTIGATION_DEFAULTS.synth.baseURL
+      )
+    },
+    initTimeoutMs: INVESTIGATION_DEFAULTS.harnessInitTimeoutMs
+  };
+  if (args.alerts && args.alerts.length > 0) {
+    request.context = {
+      alerts: args.alerts.map(coerceFiringAlert),
+      telemetry,
+      ...service ? { service } : {},
+      ...repos ? { repos } : {},
+      ...logs ? { logs } : {}
+    };
+  } else {
+    request.alert = args.alert;
+    request.telemetry = telemetry;
+    if (service) request.service = service;
+    if (repos) request.repos = repos;
+    if (logs) request.logs = logs;
+  }
+  return engineResolveInvestigation(request);
+}
+function toSandboxLimits(limits) {
+  const out = {
+    ...limits.wall_clock_ms ? { wallClockMs: limits.wall_clock_ms } : {},
+    ...limits.memory_mb ? { memoryMb: limits.memory_mb } : {},
+    ...limits.cpu_cores ? { cpuCores: limits.cpu_cores } : {}
+  };
+  return Object.keys(out).length > 0 ? out : void 0;
+}
+function selectService(args, config) {
+  const name = args.service ?? pickServiceLabel(args.alerts?.[0] ?? args.alert);
+  if (!name) return void 0;
+  const cfg = config.services[name];
+  if (!cfg) return void 0;
+  return {
+    name,
+    ...cfg.tier ? { tier: cfg.tier } : {},
+    ...cfg.repo ? { repo: cfg.repo } : {},
+    ...cfg.depends_on.length > 0 ? { dependsOn: cfg.depends_on } : {}
+  };
+}
+
 // src/cli/investigate.ts
 var investigate_default = defineCommand({
   meta: {
@@ -181,7 +301,7 @@ var investigate_default = defineCommand({
         if (!quiet) consola.log(msg);
       };
       const piped = await parseStdin();
-      const cwd = args.repo ? resolve(args.repo) : process.cwd();
+      const cwd = args.repo ? resolve2(args.repo) : process.cwd();
       const config = await loadConfig({
         ...args.config ? { configPath: args.config } : {},
         cwd,
@@ -271,7 +391,7 @@ var investigate_default = defineCommand({
         }
         const report = outcome.report;
         if (args.output) {
-          const outPath = resolve(args.output);
+          const outPath = resolve2(args.output);
           await writeFile(
             outPath,
             `${JSON.stringify(report, null, 2)}
@@ -301,12 +421,12 @@ var investigate_default = defineCommand({
   }
 });
 function collectAllowedDomains(config) {
-  const llmBaseUrl = process.env.OLLAMA_BASE_URL ?? process.env.OPENAI_BASE_URL ?? INVESTIGATION_DEFAULTS.synth.baseURL;
+  const llmBaseUrl = process.env.OLLAMA_BASE_URL ?? process.env.OPENAI_BASE_URL ?? INVESTIGATION_DEFAULTS2.synth.baseURL;
   const urls = [
     llmBaseUrl,
-    config.telemetry.prometheus_url ?? INVESTIGATION_DEFAULTS.telemetry.prometheusUrl,
-    config.telemetry.alertmanager_url ?? INVESTIGATION_DEFAULTS.telemetry.alertmanagerUrl,
-    config.telemetry.api_url ?? INVESTIGATION_DEFAULTS.telemetry.apiUrl,
+    config.telemetry.prometheus_url ?? INVESTIGATION_DEFAULTS2.telemetry.prometheusUrl,
+    config.telemetry.alertmanager_url ?? INVESTIGATION_DEFAULTS2.telemetry.alertmanagerUrl,
+    config.telemetry.api_url ?? INVESTIGATION_DEFAULTS2.telemetry.apiUrl,
     config.logs.url
   ];
   const hosts = /* @__PURE__ */ new Set();
@@ -444,6 +564,8 @@ function renderNextStep(s) {
 export {
   resolveRepoSlug,
   createFileSessionStore,
+  isSynthConfigured,
+  resolveInvestigation,
   investigate_default,
   collectAllowedDomains,
   resolveRunSandbox,