@expo/code-review-cli 0.14.0 → 0.15.0

package/README.md

@@ -4,7 +4,10 @@ A config-driven, multi-agent AI code reviewer. Specialist agents review a diff i
 parallel; a coordinator consolidates their findings into one structured review.
 The same engine runs locally (advisory) and in CI (posts one PR comment). The CLI
 is the **engine** — each repo supplies its own agents and settings under
-`.expo-code-review/`, so behavior is configured per-repo, not baked in.
+`.expo-agents/code-review/`, so behavior is configured per-repo, not baked in.
+(Repos set up before 0.15 keep their `.expo-code-review/` directory: every command
+looks for the new name first and falls back to the old one, and `ecr init` reuses
+an existing legacy directory rather than starting a second one.)
 
 > **Status: experimental.** Comment-only and non-blocking — it never blocks a merge
 > and never auto-approves. See [`ROADMAP.md`](./ROADMAP.md).
@@ -94,7 +97,7 @@ here ([LLP 0001](./llp/0001-trust-model.principles.md)) is built around that:
 ## Usage
 
 Run via `npx @expo/code-review-cli <command>` (or the `ecr` / `expo-code-review`
-binary once installed). On a repo that already has `.expo-code-review/` set up,
+binary once installed). On a repo that already has `.expo-agents/code-review/` set up,
 getting model credentials for local runs is one command:
 
 ```bash
@@ -108,7 +111,7 @@ package.
 ### First-time setup
 
 ```bash
-# 1. Scaffold .expo-code-review/ + a CI workflow (--no-workflow to skip)
+# 1. Scaffold .expo-agents/code-review/ + a CI workflow (--no-workflow to skip)
 npx @expo/code-review-cli init
 # 2. Get model credentials — guided; prints the export lines for your shell config
 npx @expo/code-review-cli setup-auth
@@ -142,7 +145,7 @@ ecr review --pr 123
 ecr review --pr 123 --post
 # Preview once, save the exact result, and post it later without another model run
 ecr review --repo owner/repo --pr 123 --save-review --json
-ecr post-review --artifact .expo-code-review/.runs/deferred/<artifact>.json --repo owner/repo --pr 123
+ecr post-review --artifact .expo-agents/code-review/.runs/deferred/<artifact>.json --repo owner/repo --pr 123
 ```
 
 Options (most to least common):
@@ -178,7 +181,7 @@ is a ready example to adapt.
 
 | Command | What it does |
 | --- | --- |
-| `ecr init [--no-workflow] [--force]` | Scaffold `.expo-code-review/` (config, agents, prompts) + a CI workflow. |
+| `ecr init [--no-workflow] [--force]` | Scaffold `.expo-agents/code-review/` (config, agents, prompts) + a CI workflow. |
 | `ecr init --monorepo` | …and add a `routing.jsonc` routing manifest (one default scope). |
 | `ecr init --scope <dir>` | Scaffold a per-team scope under `<dir>` and register it in the manifest. |
 | `ecr setup-auth [--yes]` | Walk through getting model credentials for local runs (ChatGPT/Claude sign-in and/or API keys), printing the `export` lines for your shell config. |
@@ -215,7 +218,7 @@ Markdown, `//` in JSONC):
 
 A target is a file, a `dir/`, `glob:<pattern>`, `file#symbol`, or `doc.md#heading` —
 never a line number (line numbers rot without any signal). The check is strict on
-purpose: any backticked token in `.expo-code-review/` that names something that
+purpose: any backticked token in `.expo-agents/code-review/` that names something that
 exists in the repo **must** be a ref, because stale citations are exactly the ones
 nobody annotated. Mark the rare false positive once with
 `<!-- @ref-ignore knex.raw() -->`. Refs are always repo-root-relative, including in
@@ -274,8 +277,8 @@ The boundary, in brief:
   many discovery and page fetches, so each call reports its own request ledger and
   the run reports totals.
 - **Root-only in routed monorepos** (it starts a host process); scope configs
-  cannot alter it. Result-cache reuse is disabled while research is enabled,
-  because web content can change without a config change.
+  cannot alter it. Research results are fetched and audited per run; cached review
+  results remain keyed by the ordinary trusted review inputs and make no network call.
 
 Full detail — providers, query grammar, `fetch_platform_doc` modes, provenance and
 citation grounding: [LLP 0013](./llp/0013-platform-research.explainer.md).
@@ -291,18 +294,18 @@ and no locking.
 
 ```
 your-monorepo/
-  .expo-code-review/
+  .expo-agents/code-review/
     routing.jsonc          # the manifest — infra-owned, ordered scope list + locked defaults
     config.jsonc           # the default/root scope; the ONLY place auth/tokenEnv lives
     shared.md coordinator.md agents/
   apps/
-    api/.expo-code-review/{config.jsonc(NO auth),coordinator.md,agents/}   # api team
-    web/.expo-code-review/{config.jsonc(NO auth),coordinator.md,agents/}   # web team
+    api/.expo-agents/code-review/{config.jsonc(NO auth),coordinator.md,agents/}   # api team
+    web/.expo-agents/code-review/{config.jsonc(NO auth),coordinator.md,agents/}   # web team
   .github/workflows/expo-code-review.yml   # unchanged shape: one workflow, one `ecr ci`
 ```
 
 ```jsonc
-// .expo-code-review/routing.jsonc
+// .expo-agents/code-review/routing.jsonc
 {
   // Central guardrails every scope inherits and CANNOT override.
   "defaults": {
@@ -322,7 +325,7 @@ your-monorepo/
 ```
 
 ```jsonc
-// apps/api/.expo-code-review/config.jsonc  (the api team owns this)
+// apps/api/.expo-agents/code-review/config.jsonc  (the api team owns this)
 {
   // NO "auth" block — locked centrally; a tokenEnv here is rejected by loader + CI guard.
   "model": "anthropic/claude-sonnet-5",
@@ -378,8 +381,8 @@ Enforced in code and by an independent CI guard step, not by convention:
   itself, so even a custom workflow that checks out the head still gets
   base-commit configuration.
 
-Enforce ownership with CODEOWNERS: `/.expo-code-review/routing.jsonc @your-infra`,
-`/apps/api/.expo-code-review/ @your-api-team`. Full detail:
+Enforce ownership with CODEOWNERS: `/.expo-agents/code-review/routing.jsonc @your-infra`,
+`/apps/api/.expo-agents/code-review/ @your-api-team`. Full detail:
 [LLP 0006](./llp/0006-config-schema-loading-routing.explainer.md) (routing) and
 [LLP 0001](./llp/0001-trust-model.principles.md) (trust model).
 
@@ -396,7 +399,7 @@ Enforce ownership with CODEOWNERS: `/.expo-code-review/routing.jsonc @your-infra
 - **Chunking** — small PRs run in a single pass; large PRs are split into chunks
   bounded by changed lines, plus one combined **cross-cutting pass** that looks
   for issues spanning multiple changed files across every agent's concern.
-- **Agents** — every `.md` file in `.expo-code-review/agents/` is an agent. They
+- **Agents** — every `.md` file in `.expo-agents/code-review/agents/` is an agent. They
   run in parallel with read-only repo tools (`read`/`grep`/`glob`/`list`).
 - **Coordinator** — a single pass that dedupes, re-judges severity, and produces
   the final `{ decision, findings, summary }`.
@@ -426,7 +429,7 @@ Every run reports what it spent and how much was served from the prompt cache, i
 three places: one `Token usage — …` line in the job log, a per-pass table + cache
 hit rate in the GitHub Actions step summary (which also preserves each run's posted
 comment, since the PR comment is updated in place), and one JSON line per run in
-`.expo-code-review/.runs/reviews.jsonl` (uploaded as a CI artifact) with per-pass
+`.expo-agents/code-review/.runs/reviews.jsonl` (uploaded as a CI artifact) with per-pass
 tokens, raw per-agent findings, bounded reviewer traces, and coverage notes.
 
 Each reviewer can also return a compact trace (up to three concrete checks and two
@@ -452,10 +455,10 @@ cacheable size (~1–4K tokens) show `cache read 0` — expected, not a bug.
 </details>
 
 <details>
-<summary><b>Configuration — <code>.expo-code-review/</code></b></summary>
+<summary><b>Configuration — <code>.expo-agents/code-review/</code></b></summary>
 
 ```
-.expo-code-review/
+.expo-agents/code-review/
   config.jsonc        # model, policy, noise, auth, break-glass, comment tag
   shared.md           # instructions prepended to every agent (optional)
   coordinator.md      # the consolidation prompt (required)
@@ -480,7 +483,7 @@ temperature: 0.1
 ```
 
 For a real-world example, see eas-cli's
-[`.expo-code-review/`](https://github.com/expo/eas-cli/tree/main/.expo-code-review)
+[`.expo-agents/code-review/`](https://github.com/expo/eas-cli/tree/main/.expo-code-review)
 — correctness/security/consistency agents, a stronger model for security, and
 per-repo `noise.additionalIgnores`.
 
@@ -651,6 +654,44 @@ the defaults are asymmetric: [LLP 0011](./llp/0011-author-feedback.explainer.md)
 
 </details>
 
+<details>
+<summary><b>Inline PR comments (findings on the diff line)</b></summary>
+
+Off by default. When enabled, each finding anchored to a line that is actually in
+the PR's diff is posted as an inline review comment on that line, carrying the
+full rationale, sources, and suggestion. The main comment still lists every
+finding, but an inlined one renders short — title, links, category, id, and a
+one-line rationale — plus a `💬 inline comment` link to the thread. The main
+comment remains the single durable state store: `/dismiss`, embedded state, and
+reply adjudication are unchanged.
+
+```jsonc
+"inline": {
+  "enabled": false,
+  "maxComments": 20   // per PR (single comment mode) / per scope (per-scope mode)
+}
+```
+
+Behavior notes:
+
+- **Threads converge, never churn.** Each inline comment carries a per-finding
+  marker and is patched in place across re-reviews. The cap is sticky: a live
+  thread is never evicted to create a new one. A finding that leaves the set is
+  stubbed if humans replied in its thread (never deleted), deleted only when bare.
+- **Fail-safe teardown.** A failed run, a `--scopes` partial run, or a truncated
+  aggregate never tears threads down — teardown only runs when the target set is
+  provably complete. Creates are skipped (and logged) when the PR head moved
+  during the review.
+- **Replies on inline threads count as author feedback.** Replying in a thread
+  matches the reply to that finding structurally; clearing still requires the
+  `id:…` token in the replier's own words, same as main-comment replies.
+- **Notification fan-out.** The first enabled run on a PR sends one notification
+  per created inline comment; `maxComments` bounds it.
+- **Disabling later** leaves existing threads up (the sync no longer runs); a
+  comment-mode switch — or the reporter's clear path — stubs/removes them.
+
+</details>
+
 <details>
 <summary><b>External context (--context-file)</b></summary>
 
@@ -680,7 +721,7 @@ variables: `ATLANTIS_BOT_LOGIN` (the Atlantis bot's comment login, e.g.
 <details>
 <summary><b>Run logs</b></summary>
 
-Each run appends a JSON line to `.expo-code-review/.runs/reviews.jsonl` with the
+Each run appends a JSON line to `.expo-agents/code-review/.runs/reviews.jsonl` with the
 inputs, decision, finding count, duration, per-agent cost, and aggregate token
 usage (incl. prompt-cache read/write counts) — for auditing and measuring
 cost/latency/cache reuse over time. It also records the same bounded `reviewTrace`
@@ -689,7 +730,7 @@ one-line summary to the terminal / CI job log at the end of each run, so cache r
 is visible even in CI (where the run log is ephemeral).
 
 `ecr review --save-review` additionally writes a versioned artifact under
-`.expo-code-review/.runs/deferred/` with owner-only permissions. It contains the
+`.expo-agents/code-review/.runs/deferred/` with owner-only permissions. It contains the
 verified final review and bounded feedback metadata, but no credential. `ecr
 post-review` schema-validates it and refuses to post if its explicit repo/PR, live
 head commit, or local comment-policy fingerprint no longer matches.

package/build/commands/ci.js

@@ -1,7 +1,7 @@
 // @ref LLP 0007#ecr-ci-the-trusted-root-run — fails CLOSED: trusted-root materialization failure never falls back to reading the checkout
 import { readFile } from "node:fs/promises";
 import path from "node:path";
-import { CONFIG_DIRNAME, hasScopeConfig, loadAuthFromRoot, loadReviewConfig, loadScopeConfig, tokenEnvMismatch, } from "../config/load.js";
+import { configDirFor, hasScopeConfig, loadAuthFromRoot, loadReviewConfig, loadScopeConfig, tokenEnvMismatch, } from "../config/load.js";
 import { loadRoutingManifest, resolveScopes, scopedCommentTag, scopePassesBudgetMs, formatOwnerTable, } from "../config/routing.js";
 import { repoRoot, resolveTrustedTool, run } from "../core/exec.js";
 import { errorMessage, publicFailureReason } from "../core/util.js";
@@ -390,7 +390,7 @@ function resolveStackConfirm(stack, noStackAware) {
  * `.expo-code-review/.runs/reviews.jsonl` from the workspace as an artifact.
  */
 function workspaceRunsDir(cwd) {
-    return path.join(cwd, CONFIG_DIRNAME, ".runs");
+    return path.join(configDirFor(cwd), ".runs");
 }
 /**
  * The pre-routing single-config path. Kept byte-for-byte equivalent so that with no
@@ -446,6 +446,7 @@ async function runLegacyCi(source, repo, prNumber, cwd, configRoot, options) {
         breakGlassMarker: config.breakGlassMarker,
         cwd,
         feedback: config.feedback,
+        inline: config.inline,
         headSha,
     });
     try {
@@ -554,6 +555,10 @@ async function runLegacyCi(source, repo, prNumber, cwd, configRoot, options) {
                 findings: [],
                 summary: `⚠️ The AI reviewer failed to run, so this change was **not** reviewed:\n\n> ${publicFailureReason(error)}`,
                 incomplete: [],
+                // A failed run's empty findings list proves nothing: this flag is what keeps
+                // the inline sync additive-only (no thread teardown) — and it renders the
+                // accurate "No review" decision label.
+                couldNotComplete: true,
             });
         }
         catch (postError) {
@@ -568,6 +573,10 @@ function failureReview(scopeName, reason) {
         findings: [],
         summary: `⚠️ The AI reviewer failed to run for scope **${scopeName}**, so those changes were **not** reviewed:\n\n> ${reason}`,
         incomplete: [],
+        // Empty-but-not-clean: keeps the inline sync additive-only for the whole
+        // aggregate (a failed scope's findings may still be live on the PR) and renders
+        // the accurate "No review" label in the scope table.
+        couldNotComplete: true,
     };
 }
 // @ref LLP 0007#routed-ci-fan-out [implements] — root tag wins; sequential per-scope budgets; partial --scopes merges prior state
@@ -704,6 +713,7 @@ async function runRoutedCi(source, manifest, repo, prNumber, cwd, configRoot, op
         // Root-only feedback config (see loadScopeConfig): lets a reporter posting with
         // no explicit records match replies itself (annotate mode) at report time.
         feedback: rootConfig.feedback,
+        inline: rootConfig.inline,
         headSha,
     });
     // comment:'single' mode: every active scope's feedback seam AND the final
@@ -900,7 +910,12 @@ async function runRoutedCi(source, manifest, repo, prNumber, cwd, configRoot, op
             const aggFeedback = feedbackNeedsRunSeam(rootConfig.feedback)
                 ? mergeAggregateFeedback(results, finalResults, aggState?.feedback ?? [], rootConfig.feedback, headSha, aggState?.pins)
                 : undefined;
-            await aggregate.reportAggregate(finalResults, resolution.unmatched, aggFeedback);
+            // A --scopes partial run carries the other scopes out of (possibly truncated)
+            // embedded state, so its target set is incomplete: inline teardown must not
+            // run (failed scopes are handled inside reportAggregate itself).
+            await aggregate.reportAggregate(finalResults, resolution.unmatched, aggFeedback, {
+                inlineTeardown: !scopesFilter,
+            });
         }
         // Clean up any per-scope comments from a previous per-scope run. A partial run
         // only ever touches the named scopes' comments.

package/build/commands/dismiss.js

@@ -84,6 +84,8 @@ export async function dismissCommand(argv, mode) {
             // feedback policy in force now — without it a reply-cleared finding would be
             // un-hidden by an unrelated /dismiss.
             feedback: config.feedback,
+            // Lets the dismissal stub/revive the finding's inline thread (additive-only).
+            inline: config.inline,
         });
         const result = await reporter.applyDismissal(mode === "add" ? args.ids : [], mode === "remove" ? args.ids : [], args.by, args.reason);
         if (mode === "add") {

package/build/commands/doctor.js

@@ -1,5 +1,5 @@
 // @ref LLP 0007#doctor-and-setup-auth — a preflight that must never disagree with a real run
-import { loadReviewConfig, loadScopeConfig, loadAuthFromRoot, hasConfig, resolveConfigDir, tokenEnvMismatch, } from "../config/load.js";
+import { loadReviewConfig, loadScopeConfig, loadAuthFromRoot, hasConfig, CONFIG_DIRNAME, resolveConfigDir, tokenEnvMismatch, } from "../config/load.js";
 import { loadRoutingManifest, resolveScopes, scopePassesBudgetMs, formatOwnerTable, } from "../config/routing.js";
 import readline from "node:readline/promises";
 import { setupAuthCommand } from "./setup-auth.js";
@@ -198,7 +198,7 @@ export async function doctorCommand(argv = []) {
         info("gh CLI not on PATH — only needed for `ecr ci` (posting PR comments)");
     }
     if (!hasConfig(root)) {
-        line(false, `no ${".expo-code-review"}/config.jsonc (run \`ecr init\`)`);
+        line(false, `no ${CONFIG_DIRNAME}/config.jsonc (run \`ecr init\`)`);
     }
     else {
         try {
@@ -394,7 +394,7 @@ async function listScopes(root) {
         return;
     }
     if (!manifest) {
-        process.stdout.write(`No ${".expo-code-review"}/routing.jsonc — run \`ecr init --monorepo\`.\n`);
+        process.stdout.write(`No ${CONFIG_DIRNAME}/routing.jsonc — run \`ecr init --monorepo\`.\n`);
         process.exitCode = 0;
         return;
     }

package/build/commands/init.js

@@ -3,14 +3,14 @@ import { cp, mkdir, readFile, writeFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { CONFIG_DIRNAME } from "../config/load.js";
+import { CONFIG_DIRNAME, configDirFor } from "../config/load.js";
 import { ROUTING_FILENAME } from "../config/routing.js";
 import { RoutingScopeSchema } from "../config/schema.js";
 import { FORBIDDEN_TOKEN_ENVS } from "../core/auth.js";
 import { repoRoot } from "../core/exec.js";
 import { errorMessage } from "../core/util.js";
 const TEMPLATES_DIR = fileURLToPath(new URL("../../templates/", import.meta.url));
-const USAGE = `ecr init — scaffold .expo-code-review/ in the current repo
+const USAGE = `ecr init — scaffold .expo-agents/code-review/ in the current repo (a legacy .expo-code-review/ is reused)
 
 Usage:
   ecr init [--no-workflow] [--force]      Scaffold the root config (+ CI workflow)
@@ -19,8 +19,8 @@ Usage:
                                           register it in the root routing.jsonc
 
 Options:
-  --monorepo      Also write .expo-code-review/routing.jsonc (routing manifest)
-  --scope <dir>   Scaffold <dir>/.expo-code-review/ (no auth) + add a scope entry
+  --monorepo      Also write routing.jsonc in the setup dir (routing manifest)
+  --scope <dir>   Scaffold <dir>/.expo-agents/code-review/ (no auth) + add a scope entry
   --no-workflow   Skip writing the CI workflows (review, command, and dismiss
                   under .github/workflows/)
   --token-env <name[,name…]>
@@ -76,7 +76,7 @@ async function scaffold(argv) {
         throw new Error("--token-env customizes the CI workflows; drop it or remove --no-workflow");
     }
     const root = (await repoRoot()) ?? process.cwd();
-    const configDir = path.join(root, CONFIG_DIRNAME);
+    const configDir = configDirFor(root); // an existing legacy .expo-code-review/ is kept, never doubled
     // A non-default --token-env only takes effect through the review workflows,
     // but existing workflow files are skipped (not rewritten) without --force —
     // the flag would silently never reach CI while the next steps claim the
@@ -201,7 +201,7 @@ async function scaffoldScope(argv, scopeDirRaw) {
         throw new Error(`scope dir "${scopeDir}" yields an invalid scope entry (${parsed.error.issues[0]?.message}); ` +
             `rename the directory or add the scope to ${CONFIG_DIRNAME}/${ROUTING_FILENAME} manually`);
     }
-    const configDir = path.join(root, scopeDir, CONFIG_DIRNAME);
+    const configDir = configDirFor(path.join(root, scopeDir));
     await mkdir(configDir, { recursive: true });
     const created = [];
     const skipped = [];

package/build/commands/post-review.js

@@ -113,6 +113,7 @@ export async function postReviewCommand(argv) {
             breakGlassMarker: config.breakGlassMarker,
             cwd,
             feedback: config.feedback,
+            inline: config.inline,
             headSha,
         });
         const result = await publishDeferredReview(reporter, artifact, async () => {

package/build/commands/review.js

@@ -242,6 +242,8 @@ export async function reviewCommand(argv) {
                         cwd,
                         // Root-only feedback config (loadScopeConfig inherits it from the root).
                         feedback: config.feedback,
+                        // Root-only too (loadScopeConfig inherits it from the root).
+                        inline: config.inline,
                         headSha: await reviewedHeadSha(source),
                     })
                     : null;
@@ -315,6 +317,7 @@ export async function reviewCommand(argv) {
                 breakGlassMarker: config.breakGlassMarker,
                 cwd,
                 feedback: config.feedback,
+                inline: config.inline,
                 headSha,
             })
             : null;

package/build/commands/verify-config.js

@@ -1,7 +1,7 @@
 // @ref LLP 0007#verify-config-the-config-guard — the CI trust guard that runs before the loaders are trusted, so it deliberately does not use them
 import { readdir, readFile } from "node:fs/promises";
 import path from "node:path";
-import { CONFIG_DIRNAME, stripJsonComments, stripTrailingCommas } from "../config/load.js";
+import { CONFIG_DIRNAME, configDirFor, isConfigDirPath, stripJsonComments, stripTrailingCommas, } from "../config/load.js";
 import { ROUTING_FILENAME } from "../config/routing.js";
 import { repoRoot } from "../core/exec.js";
 import { errorMessage } from "../core/util.js";
@@ -52,9 +52,7 @@ async function discoverConfigFiles(root) {
                 }
                 await walk(path.join(dir, entry.name));
             }
-            else if (entry.isFile() &&
-                path.basename(dir) === CONFIG_DIRNAME &&
-                CONFIG_FILENAMES.has(entry.name)) {
+            else if (entry.isFile() && isConfigDirPath(dir) && CONFIG_FILENAMES.has(entry.name)) {
                 found.push(path.join(dir, entry.name));
             }
         }
@@ -112,7 +110,7 @@ function extractFacts(file, parsed) {
  */
 export async function verifyConfig(root, options = {}) {
     const findings = [];
-    const rootConfigDir = path.join(root, CONFIG_DIRNAME);
+    const rootConfigDir = configDirFor(root);
     const rel = (file) => path.relative(root, file) || path.basename(file);
     const files = await discoverConfigFiles(root);
     const tokenEnvOccurrences = [];

package/build/config/load.js

@@ -7,7 +7,22 @@ import { existsSync } from "node:fs";
 import path from "node:path";
 import { ReviewConfigSchema, ScopeReviewConfigSchema } from "./schema.js";
 import { toolMap } from "../core/tools.js";
-export const CONFIG_DIRNAME = ".expo-code-review";
+/**
+ * The setup directory. `.expo-agents/code-review/` is the home from 0.15.0 —
+ * one `.expo-agents/` directory holds every Expo agent tool's per-repo files
+ * (code-review, verify) instead of one dot directory per tool at the root.
+ * The pre-0.15 `.expo-code-review/` keeps working unchanged: every lookup
+ * takes whichever of the two exists (new first), and scaffolding writes into
+ * an existing legacy directory rather than starting a second one.
+ */
+export const CONFIG_DIRNAME = path.join(".expo-agents", "code-review");
+export const LEGACY_CONFIG_DIRNAME = ".expo-code-review";
+export const CONFIG_DIRNAMES = [CONFIG_DIRNAME, LEGACY_CONFIG_DIRNAME];
+/** Does this directory path name a setup dir (either spelling)? */
+export function isConfigDirPath(dir) {
+    const normalized = path.normalize(dir);
+    return CONFIG_DIRNAMES.some((name) => normalized === name || normalized.endsWith(path.sep + name));
+}
 /** Stack config for a scope load (where `stack` is schema-rejected and absent). */
 const STACK_CONFIG_DEFAULTS = {
     enabled: false,
@@ -26,6 +41,11 @@ const FEEDBACK_CONFIG_DEFAULTS = {
     protectedCategories: ["secrets", "security"],
     maxAdjudications: 10,
 };
+/** Inline-comment config for a scope load (where `inline` is schema-rejected). */
+const INLINE_CONFIG_DEFAULTS = {
+    enabled: false,
+    maxComments: 20,
+};
 /** Research defaults for a scope load (where `research` is schema-rejected). */
 const RESEARCH_CONFIG_DEFAULTS = {
     enabled: false,
@@ -35,21 +55,33 @@ const RESEARCH_CONFIG_DEFAULTS = {
 };
 /** Default OpenCode tool toggles for a reviewer: read the repo, never mutate it. */
 const DEFAULT_AGENT_TOOLS = toolMap(["read", "grep", "glob", "list"]);
-export function configDirFor(repoRoot) {
-    return path.join(repoRoot, CONFIG_DIRNAME);
+/**
+ * The setup dir under `base`: `.expo-agents/code-review/` when it exists, else
+ * the legacy `.expo-code-review/` when THAT exists, else the new name (for
+ * messages and for scaffolding a fresh repo). Works for the repo root and for
+ * scope directories alike.
+ */
+export function configDirFor(base) {
+    for (const name of CONFIG_DIRNAMES) {
+        const candidate = path.join(base, name);
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    return path.join(base, CONFIG_DIRNAME);
 }
 /**
  * Resolve the config directory: an explicit override (absolute or repo-relative)
- * → the ECR_CONFIG_DIR env var → the repo's default `.expo-code-review/`. This is
- * the escape hatch (graft 1); with neither override present the result is exactly
- * `configDirFor(repoRoot)`, so the default behavior is byte-identical.
+ * → the ECR_CONFIG_DIR env var → the repo's default setup dir (new name, then
+ * legacy). This is the escape hatch (graft 1); with neither override present the
+ * result is exactly `configDirFor(repoRoot)`.
  */
 export function resolveConfigDir(repoRoot, override) {
     const chosen = override ?? process.env.ECR_CONFIG_DIR;
     if (chosen) {
         return path.isAbsolute(chosen) ? chosen : path.join(repoRoot, chosen);
     }
-    return path.join(repoRoot, CONFIG_DIRNAME);
+    return configDirFor(repoRoot);
 }
 export function hasConfig(repoRoot, options = {}) {
     // Resolve the same way loadReviewConfig does (incl. the ECR_CONFIG_DIR escape
@@ -162,6 +194,8 @@ async function loadConfigDir(dir, schema) {
         // for a scope config and the defaults stand in (unused — the command layer
         // reads the ROOT config's feedback values; the comment lifecycle is global).
         feedback: parsed.feedback ?? FEEDBACK_CONFIG_DEFAULTS,
+        // Root-only, same reasoning as feedback.
+        inline: parsed.inline ?? INLINE_CONFIG_DEFAULTS,
     };
     return { config, raw: rawObject };
 }
@@ -231,7 +265,7 @@ export function hasScopeConfig(root, scope) {
     if (scope.config === ".") {
         return true;
     }
-    const dir = path.join(root, scope.config, CONFIG_DIRNAME);
+    const dir = configDirFor(path.join(root, scope.config));
     return existsSync(path.join(dir, "config.jsonc")) || existsSync(path.join(dir, "config.json"));
 }
 /**
@@ -258,7 +292,7 @@ export async function loadScopeConfig(root, scope, manifest, rootConfig) {
         if (resolvedScope !== resolvedRoot && !resolvedScope.startsWith(resolvedRoot + path.sep)) {
             throw new Error(`scope "${scope.name}": config "${scope.config}" resolves outside the repo checkout`);
         }
-        const dir = path.join(root, scope.config, CONFIG_DIRNAME);
+        const dir = configDirFor(path.join(root, scope.config));
         const { config } = await loadConfigDir(dir, ScopeReviewConfigSchema);
         base = config;
         // Non-default scopes never carry their own marker (the scope schema rejects
@@ -296,6 +330,7 @@ export async function loadScopeConfig(root, scope, manifest, rootConfig) {
         // run the default policy instead of the repo's real one.
         stack: rootConfig.stack,
         feedback: rootConfig.feedback,
+        inline: rootConfig.inline,
         research: rootConfig.research,
         scopeName: scope.name,
     };

package/build/config/schema.js

@@ -216,6 +216,20 @@ export const ReviewConfigSchema = z.object({
         protectedCategories: ["secrets", "security"],
         maxAdjudications: 10,
     }),
+    // Inline PR review comments for findings anchored to a line in the diff: the
+    // main comment stays the durable state store and renders such findings short,
+    // linking to the inline thread. ROOT-ONLY (the comment lifecycle is global) and
+    // off by default — a feature that mutates N comments per run earns trust with
+    // field data first. Turning it off later leaves existing threads up (documented);
+    // clear() still sweeps them on comment-mode switches.
+    inline: z
+        .object({
+        enabled: z.boolean().default(false),
+        // Cap on inline comments PER REPORTER: per PR in single/legacy comment mode,
+        // per scope in per-scope mode. Bounds create-notification fan-out and API use.
+        maxComments: z.number().int().positive().default(20),
+    })
+        .default({ enabled: false, maxComments: 20 }),
 });
 /** One routing scope: ordered globs → a directory containing .expo-code-review/. */
 export const RoutingScopeSchema = z.object({
@@ -317,6 +331,7 @@ export const ScopeReviewConfigSchema = ReviewConfigSchema.omit({
     stack: true,
     feedback: true,
     research: true,
+    inline: true,
 }).extend({
     auth: z
         .never({ error: "auth is locked to the root config; remove it from this scope config" })
@@ -342,4 +357,9 @@ export const ScopeReviewConfigSchema = ReviewConfigSchema.omit({
         error: "research is locked to the root config because it starts a trusted host process; remove it from this scope config",
     })
         .optional(),
+    inline: z
+        .never({
+        error: "inline is locked to the root config (the comment lifecycle is global); remove it from this scope config",
+    })
+        .optional(),
 });

package/build/core/config-refs.js

@@ -3,7 +3,7 @@
 // @ref LLP 0012#unannotated-citations-are-broken-refs — a path-like backtick token that is not a ref fails the check
 import { readdir, readFile, stat } from "node:fs/promises";
 import path from "node:path";
-import { CONFIG_DIRNAME, stripJsonComments, stripTrailingCommas } from "../config/load.js";
+import { CONFIG_DIRNAME, LEGACY_CONFIG_DIRNAME, configDirFor, stripJsonComments, stripTrailingCommas, } from "../config/load.js";
 import { ROUTING_FILENAME } from "../config/routing.js";
 import { git, pathInside } from "./exec.js";
 import { matchesIgnore } from "./noise.js";
@@ -448,10 +448,18 @@ export async function discoverSetupDirs(root) {
                 continue;
             }
             const child = path.join(dir, entry.name);
-            if (entry.name === CONFIG_DIRNAME) {
+            if (entry.name === LEGACY_CONFIG_DIRNAME) {
                 found.push(child);
                 continue; // a setup dir never nests another
             }
+            if (entry.name === ".expo-agents") {
+                // The shared Expo agent-tools dir: only its code-review/ child is ours.
+                const setup = path.join(dir, CONFIG_DIRNAME);
+                if ((await pathKind(setup)) === "dir") {
+                    found.push(setup);
+                }
+                continue;
+            }
             // Other dot dirs are skipped wholesale: `.claude/worktrees/` holds checkouts of
             // this same repo, whose setup dirs would otherwise be swept as if they were scopes.
             if (entry.name === "node_modules" || entry.name.startsWith(".")) {
@@ -542,7 +550,7 @@ async function checkRoutingManifest(file, index, rootAgentIds) {
         }
         const configDir = typeof entry.config === "string" ? entry.config : null;
         if (configDir) {
-            const setupDir = path.resolve(index.root, configDir, CONFIG_DIRNAME);
+            const setupDir = configDirFor(path.resolve(index.root, configDir));
             if (!pathInside(setupDir, index.root)) {
                 problems.push({
                     file: relative,
@@ -556,7 +564,7 @@ async function checkRoutingManifest(file, index, rootAgentIds) {
                     file: relative,
                     line: 1,
                     kind: "structural",
-                    problem: `scope "${name}" has no ${configDir}/${CONFIG_DIRNAME}/ directory`,
+                    problem: `scope "${name}" has no ${configDir}/${CONFIG_DIRNAME}/ (or ${LEGACY_CONFIG_DIRNAME}/) directory`,
                 });
             }
         }

package/build/core/deferred-review.js

@@ -33,6 +33,10 @@ export function reviewPostingConfigFingerprint(config) {
         commentTag: config.commentTag,
         breakGlassMarker: config.breakGlassMarker,
         feedback: config.feedback,
+        // Inline comments change what posting does (N review-comment mutations), so a
+        // saved review must not post under a different inline policy than it was
+        // saved with.
+        inline: config.inline,
     }))
         .digest("hex");
 }