muonroi-cli 1.2.0

package/src/ee/offline-queue.ts

@@ -0,0 +1,212 @@
+/**
+ * Offline queue module for Experience Engine write operations.
+ *
+ * Persists failed EE requests (feedback, extract, prompt-stale) to disk so they
+ * survive process restarts and are replayed when EE recovers.
+ *
+ * Design decisions (from CONTEXT.md):
+ *  - D-01: One JSON file per entry in ~/.muonroi-cli/ee-offline-queue/
+ *  - D-02: Timestamp-based filenames for natural FIFO ordering
+ *  - D-03: Each entry stores endpoint, body, enqueuedAt
+ *  - D-04: Cap at 100 entries; oldest deleted before writing new
+ *  - D-08: drainQueue() is fire-and-forget (returns void)
+ *  - D-11: Queue directory created lazily on first enqueue
+ *
+ * NO imports from client.ts or intercept.ts (prevents circular deps).
+ * fetchImpl and headers are passed as parameters.
+ */
+import { promises as fs } from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+// ─── Constants ────────────────────────────────────────────────────────────────
+
+const MAX_QUEUE_SIZE = 100;
+const QUEUE_DIR_NAME = "ee-offline-queue";
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+/** Queue entry shape — self-contained, no external type deps. */
+export interface QueueEntry {
+  endpoint: string; // e.g. "/api/feedback", "/api/extract", "/api/prompt-stale"
+  body: unknown; // original request payload verbatim
+  enqueuedAt: number; // Date.now() at enqueue time
+}
+
+// ─── Path helpers ─────────────────────────────────────────────────────────────
+
+/**
+ * Returns the absolute path to the offline queue directory.
+ * Consistent with auth.ts homeOverride pattern.
+ */
+export function getQueueDir(homeOverride?: string): string {
+  return path.join(homeOverride ?? os.homedir(), ".muonroi-cli", QUEUE_DIR_NAME);
+}
+
+// ─── Internal helpers ─────────────────────────────────────────────────────────
+
+/**
+ * Generate a unique filename for a new queue entry.
+ * Format: `{Date.now()}-{random4}.json` (D-02)
+ * The timestamp prefix ensures natural FIFO ordering on readdir + sort.
+ */
+function makeFilename(): string {
+  const ts = Date.now();
+  const rnd = Math.random().toString(36).slice(2, 6);
+  return `${ts}-${rnd}.json`;
+}
+
+/**
+ * Returns sorted list of .json filenames in the queue directory.
+ * Lexicographic sort on timestamp-prefixed names = chronological FIFO order.
+ *
+ * Throws ENOENT if directory does not exist — callers handle this.
+ */
+async function getSortedFiles(dir: string): Promise<string[]> {
+  const entries = await fs.readdir(dir);
+  return entries.filter((f) => f.endsWith(".json")).sort();
+}
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Persists a failed EE request to the local queue.
+ *
+ * Creates queue directory lazily (D-11).
+ * Enforces MAX_QUEUE_SIZE cap by deleting oldest entry (D-04).
+ */
+export async function enqueue(entry: QueueEntry, homeOverride?: string): Promise<void> {
+  const dir = getQueueDir(homeOverride);
+
+  // D-11: lazy init — create dir only when needed
+  await fs.mkdir(dir, { recursive: true });
+
+  const files = await getSortedFiles(dir);
+
+  // D-04: cap enforcement — drop oldest before writing new
+  if (files.length >= MAX_QUEUE_SIZE) {
+    await fs.unlink(path.join(dir, files[0])).catch(() => {
+      /* ignore if already gone */
+    });
+  }
+
+  const filename = makeFilename();
+  await fs.writeFile(path.join(dir, filename), JSON.stringify(entry), "utf8");
+
+  if (process.env.MUONROI_DEBUG) {
+    console.debug(
+      "[muonroi-cli] EE offline queue: enqueued %s (cap=%d)",
+      entry.endpoint,
+      MAX_QUEUE_SIZE,
+    );
+  }
+}
+
+/**
+ * Internal async implementation shared by drainQueue (fire-and-forget)
+ * and drainQueueAsync (awaitable, for tests).
+ *
+ * Sequential replay (D-06):
+ *  - Reads sorted queue files in FIFO order
+ *  - POSTs each entry to baseUrl + entry.endpoint
+ *  - Deletes file on HTTP success (resp.ok)
+ *  - Discards corrupt (unparseable) files silently
+ *  - Stops on HTTP failure or network error (D-07) — leaves file + remaining
+ *
+ * D-11: If queue directory doesn't exist yet, returns early (no error).
+ */
+async function drainQueueInternal(
+  fetchImpl: typeof fetch,
+  headers: Record<string, string>,
+  baseUrl: string,
+  homeOverride?: string,
+): Promise<void> {
+  const dir = getQueueDir(homeOverride);
+
+  let files: string[];
+  try {
+    files = await getSortedFiles(dir);
+  } catch {
+    // ENOENT — queue dir never created (no entries ever queued). Normal path.
+    return;
+  }
+
+  for (const file of files) {
+    const filePath = path.join(dir, file);
+
+    // Parse entry — discard corrupt files
+    let entry: QueueEntry;
+    try {
+      const raw = await fs.readFile(filePath, "utf8");
+      entry = JSON.parse(raw) as QueueEntry;
+    } catch {
+      // Corrupt JSON — delete silently and continue
+      await fs.unlink(filePath).catch(() => {});
+      continue;
+    }
+
+    // Replay the entry
+    try {
+      const resp = await fetchImpl(`${baseUrl}${entry.endpoint}`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(entry.body),
+        signal: AbortSignal.timeout(5000),
+      });
+
+      if (resp.ok) {
+        // Success — delete file and continue to next
+        await fs.unlink(filePath).catch(() => {});
+
+        if (process.env.MUONROI_DEBUG) {
+          console.debug(
+            "[muonroi-cli] EE offline queue: replayed %s",
+            entry.endpoint,
+          );
+        }
+      } else {
+        // D-07: server returned error — stop drain, leave file + remaining
+        break;
+      }
+    } catch {
+      // D-07: network failure — stop drain, leave file + remaining
+      break;
+    }
+  }
+}
+
+/**
+ * Replays queued EE requests in FIFO order.
+ *
+ * Fire-and-forget wrapper (D-08) — returns void immediately.
+ * The caller (recordCircuitSuccess in client.ts) must NOT await this.
+ *
+ * @param fetchImpl - fetch implementation (injectable for tests)
+ * @param headers   - HTTP headers to include (Content-Type + optional auth)
+ * @param baseUrl   - EE base URL (e.g. "http://localhost:8082")
+ * @param homeOverride - Optional home dir override (for tests)
+ */
+export function drainQueue(
+  fetchImpl: typeof fetch,
+  headers: Record<string, string>,
+  baseUrl: string,
+  homeOverride?: string,
+): void {
+  // D-08: fire-and-forget — the returned Promise is intentionally not awaited
+  void drainQueueInternal(fetchImpl, headers, baseUrl, homeOverride);
+}
+
+/**
+ * Awaitable version of drainQueue — for tests only.
+ *
+ * Production code must use drainQueue() (void).
+ * Tests use drainQueueAsync() to await completion before asserting.
+ */
+export async function drainQueueAsync(
+  fetchImpl: typeof fetch,
+  headers: Record<string, string>,
+  baseUrl: string,
+  homeOverride?: string,
+): Promise<void> {
+  await drainQueueInternal(fetchImpl, headers, baseUrl, homeOverride);
+}

package/src/ee/posttool.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it, vi } from "vitest";
+import type { JudgeContext } from "./judge.js";
+import type { PostToolPayload } from "./types.js";
+
+// Mock both intercept and judge modules
+// posttool is now async — mock must return a Promise so await works correctly
+const mockPosttool = vi.fn().mockResolvedValue(undefined);
+
+vi.mock("./intercept.js", () => ({
+  getDefaultEEClient: () => ({
+    posttool: mockPosttool,
+  }),
+}));
+
+vi.mock("./judge.js", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("./judge.js")>();
+  return {
+    ...actual,
+    fireFeedback: vi.fn(),
+  };
+});
+
+const mockPayload: PostToolPayload = {
+  toolName: "bash",
+  toolInput: { command: "ls" },
+  outcome: { success: true, exitCode: 0, durationMs: 10 },
+  cwd: "/tmp",
+  tenantId: "local",
+  scope: { kind: "global" },
+};
+
+describe("posttool() wrapper", () => {
+  it("calls client.posttool with payload", async () => {
+    mockPosttool.mockClear();
+    const { posttool } = await import("./posttool.js");
+    await posttool(mockPayload);
+    expect(mockPosttool).toHaveBeenCalledOnce();
+    expect(mockPosttool).toHaveBeenCalledWith(mockPayload);
+  });
+
+  it("calls fireFeedback when judgeCtx provided", async () => {
+    mockPosttool.mockClear();
+    const { posttool } = await import("./posttool.js");
+    const { fireFeedback } = await import("./judge.js");
+    const mockFF = fireFeedback as unknown as ReturnType<typeof vi.fn>;
+    mockFF.mockClear();
+
+    const ctx: JudgeContext = {
+      warningResponse: { decision: "allow", matches: [] },
+      toolName: "bash",
+      outcome: { success: true, durationMs: 10 },
+      cwdMatchedAtPretool: true,
+      diffPresent: false,
+      tenantId: "local",
+    };
+    await posttool(mockPayload, ctx);
+    expect(mockPosttool).toHaveBeenCalledOnce();
+    expect(mockFF).toHaveBeenCalledOnce();
+    expect(mockFF).toHaveBeenCalledWith(ctx);
+  });
+
+  it("does not call fireFeedback when judgeCtx is undefined", async () => {
+    mockPosttool.mockClear();
+    const { posttool } = await import("./posttool.js");
+    const { fireFeedback } = await import("./judge.js");
+    const mockFF = fireFeedback as unknown as ReturnType<typeof vi.fn>;
+    mockFF.mockClear();
+
+    await posttool(mockPayload);
+    expect(mockPosttool).toHaveBeenCalledOnce();
+    expect(mockFF).not.toHaveBeenCalled();
+  });
+
+  it("returns Promise<void> (async — awaitable by PostToolUse handler)", async () => {
+    mockPosttool.mockClear();
+    const { posttool } = await import("./posttool.js");
+    const result = posttool(mockPayload);
+    expect(result).toBeInstanceOf(Promise);
+    await result; // resolves to undefined
+  });
+});

package/src/ee/posttool.ts

@@ -0,0 +1,16 @@
+import { getDefaultEEClient } from "./intercept.js";
+import { fireFeedback, type JudgeContext } from "./judge.js";
+import type { PostToolPayload } from "./types.js";
+
+/**
+ * Call the EE posttool endpoint using the default client.
+ * Returns Promise<void> — awaitable by the PostToolUse hook handler.
+ * Errors are swallowed (fire-and-forget semantics preserved inside client).
+ *
+ * When judgeCtx is provided, also fires deterministic feedback (EE-09)
+ * and touch on FOLLOWED matches (EE-10). fireFeedback stays synchronous (B-4 preserved).
+ */
+export async function posttool(payload: PostToolPayload, judgeCtx?: JudgeContext): Promise<void> {
+  await getDefaultEEClient().posttool(payload);
+  if (judgeCtx) fireFeedback(judgeCtx);
+}

package/src/ee/prompt-stale.test.ts

@@ -0,0 +1,87 @@
+/**
+ * src/ee/prompt-stale.test.ts
+ *
+ * Unit tests for reconcilePromptStale() fire-and-forget module.
+ * Tests use vi.mock for getDefaultEEClient to inject mockPromptStale,
+ * while using real updateLastSurfacedState/resetLastSurfacedState from intercept.ts.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// Mock getDefaultEEClient to inject a controllable mockPromptStale
+vi.mock("./intercept.js", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("./intercept.js")>();
+  return {
+    ...actual,
+    getDefaultEEClient: vi.fn(),
+  };
+});
+
+import { getDefaultEEClient, getLastSurfacedState, resetLastSurfacedState, updateLastSurfacedState } from "./intercept.js";
+import { reconcilePromptStale } from "./prompt-stale.js";
+
+describe("reconcilePromptStale", () => {
+  let mockPromptStale: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    mockPromptStale = vi.fn().mockResolvedValue({ ok: true, unused: [], irrelevant: [], expired: [] });
+    vi.mocked(getDefaultEEClient).mockReturnValue({
+      promptStale: mockPromptStale,
+    } as any);
+  });
+
+  afterEach(() => {
+    resetLastSurfacedState();
+    vi.clearAllMocks();
+  });
+
+  it("is a no-op when no surfaced IDs exist (does not call promptStale)", async () => {
+    // No call to updateLastSurfacedState — surfacedIds should be []
+    const result = reconcilePromptStale("/tmp");
+    // Flush microtasks
+    await new Promise((r) => setTimeout(r, 0));
+    expect(result).toBeUndefined();
+    expect(mockPromptStale).not.toHaveBeenCalled();
+  });
+
+  it("calls promptStale with correct payload when IDs are surfaced", async () => {
+    updateLastSurfacedState(["id-1", "id-2"]);
+    reconcilePromptStale("/tmp");
+    // Flush microtasks
+    await new Promise((r) => setTimeout(r, 0));
+
+    expect(mockPromptStale).toHaveBeenCalledTimes(1);
+    const [req] = mockPromptStale.mock.calls[0];
+    expect(req.state.surfacedIds).toEqual(["id-1", "id-2"]);
+    expect(typeof req.state.timestamp).toBe("string");
+    expect(req.nextPromptMeta.trigger).toBe("auto-compact");
+    expect(req.nextPromptMeta.cwd).toBe("/tmp");
+    expect(req.nextPromptMeta.tenantId).toBe("local");
+  });
+
+  it("returns undefined (void, not a Promise)", () => {
+    updateLastSurfacedState(["id-1"]);
+    const result = reconcilePromptStale("/tmp");
+    expect(result).toBeUndefined();
+  });
+
+  it("resets surfaced state BEFORE dispatching async HTTP call", async () => {
+    updateLastSurfacedState(["id-1", "id-2"]);
+    reconcilePromptStale("/tmp");
+    // Surfaced state should be reset synchronously before async dispatch
+    expect(getLastSurfacedState().surfacedIds).toEqual([]);
+    // HTTP call still dispatched (can verify via flush)
+    await new Promise((r) => setTimeout(r, 0));
+    expect(mockPromptStale).toHaveBeenCalledTimes(1);
+  });
+
+  it("swallows errors from rejected promptStale promise (fire-and-forget)", async () => {
+    mockPromptStale.mockRejectedValue(new Error("network error"));
+    updateLastSurfacedState(["id-1"]);
+    // Should not throw
+    expect(() => reconcilePromptStale("/tmp")).not.toThrow();
+    // Allow the rejected promise to settle — should not produce unhandled rejection
+    await new Promise((r) => setTimeout(r, 10));
+    expect(mockPromptStale).toHaveBeenCalledTimes(1);
+  });
+});

package/src/ee/prompt-stale.ts

@@ -0,0 +1,39 @@
+/**
+ * src/ee/prompt-stale.ts
+ *
+ * Per-turn prompt-stale reconciliation. Called fire-and-forget from PostToolUse
+ * hook to report surfaced EE suggestions that the agent did not explicitly
+ * acknowledge via feedback(). Uses "auto-compact" trigger to avoid cross-repo
+ * server dependency (see 10-RESEARCH.md Pitfall 3).
+ *
+ * STALE-02: calls /api/prompt-stale for surfaced IDs
+ * STALE-03: fire-and-forget — returns void, never blocks
+ */
+
+import { getDefaultEEClient, getLastSurfacedState, resetLastSurfacedState } from "./intercept.js";
+import { getTenantId } from "./tenant.js";
+
+/**
+ * Fire-and-forget prompt-stale reconciliation.
+ * Called from PostToolUse hook after each tool-use turn.
+ *
+ * Returns void — caller must NOT await (B-4 budget constraint).
+ * Resets surfaced state BEFORE dispatching the async HTTP call
+ * to prevent double-reporting on rapid sequential PostToolUse events.
+ */
+export function reconcilePromptStale(cwd: string, tenantId = getTenantId()): void {
+  const { surfacedIds, timestamp } = getLastSurfacedState();
+  if (surfacedIds.length === 0) return;
+
+  // Reset before async dispatch to avoid double-report (see 10-RESEARCH.md Pitfall 2)
+  resetLastSurfacedState();
+
+  getDefaultEEClient()
+    .promptStale({
+      state: { surfacedIds, timestamp },
+      nextPromptMeta: { trigger: "auto-compact", cwd, tenantId },
+    })
+    .catch(() => {
+      // Errors swallowed — fire-and-forget (B-4)
+    });
+}

package/src/ee/render.test.ts

@@ -0,0 +1,71 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { emitMatches, renderInterceptWarning, setRenderSink } from "./render.js";
+import type { InterceptMatch } from "./types.js";
+
+const baseMatch: InterceptMatch = {
+  principle_uuid: "test-uuid-1234",
+  embedding_model_version: "nomic-embed-text-v1.5",
+  confidence: 0.85,
+  why: "It causes Y",
+  message: "Avoid editing X",
+  scope_label: "repo:foo/bar",
+  last_matched_at: "2026-04-30T00:00:00Z",
+};
+
+describe("renderInterceptWarning", () => {
+  it("renders 5-line boxed warning with confidence%, message, why, scope", () => {
+    const result = renderInterceptWarning(baseMatch);
+    const lines = result.split("\n");
+    expect(lines).toHaveLength(5);
+    expect(lines[0]).toContain("⚠ Experience Warning");
+    expect(lines[1]).toContain("85%");
+    expect(lines[1]).toContain("Avoid editing X");
+    expect(lines[2]).toContain("It causes Y");
+    expect(lines[3]).toContain("repo:foo/bar");
+    expect(lines[4]).toContain("└");
+  });
+
+  it("renders confidence as integer percentage (85% not 0.85)", () => {
+    expect(renderInterceptWarning(baseMatch)).toContain("85%");
+  });
+
+  it("renders confidence=1 as 100%", () => {
+    const match: InterceptMatch = { ...baseMatch, confidence: 1 };
+    expect(renderInterceptWarning(match)).toContain("100%");
+  });
+
+  it("renders confidence=0 as 0%", () => {
+    const match: InterceptMatch = { ...baseMatch, confidence: 0 };
+    expect(renderInterceptWarning(match)).toContain("[0%]");
+  });
+});
+
+describe("emitMatches + setRenderSink", () => {
+  let captured: string[];
+
+  beforeEach(() => {
+    captured = [];
+    setRenderSink((line) => captured.push(line));
+  });
+
+  it("emits each match via the sink", () => {
+    const matches: InterceptMatch[] = [
+      baseMatch,
+      { ...baseMatch, message: "Do not delete Z", why: "It breaks Q", confidence: 0.92 },
+    ];
+    emitMatches(matches);
+    expect(captured).toHaveLength(2);
+    expect(captured[0]).toContain("Avoid editing X");
+    expect(captured[1]).toContain("Do not delete Z");
+  });
+
+  it("does nothing for undefined matches", () => {
+    emitMatches(undefined);
+    expect(captured).toHaveLength(0);
+  });
+
+  it("does nothing for empty matches", () => {
+    emitMatches([]);
+    expect(captured).toHaveLength(0);
+  });
+});

package/src/ee/render.ts

@@ -0,0 +1,47 @@
+/**
+ * EE PreToolUse inline warning renderer.
+ *
+ * EE-02: decision='allow' with matches[] emits ⚠ [Experience] lines
+ * via a pluggable render sink (default: console.warn).
+ *
+ * Format per match (5 lines with visual border):
+ *   ┌─ ⚠ Experience Warning ──────────────────────┐
+ *   │ [{confidence}] {message}
+ *   │ Why: {why}
+ *   │ Scope: {scope_label}
+ *   └──────────────────────────────────────────────┘
+ */
+import type { InterceptMatch } from "./types.js";
+
+const BORDER_WIDTH = 46;
+const TOP_BORDER = `┌─ ⚠ Experience Warning ${"─".repeat(BORDER_WIDTH - 22)}┐`;
+const BOTTOM_BORDER = `└${"─".repeat(BORDER_WIDTH - 1)}┘`;
+
+type RenderSink = (line: string) => void;
+let _sink: RenderSink = (line) => {
+  console.warn(line);
+};
+
+export function setRenderSink(fn: RenderSink): void {
+  _sink = fn;
+}
+export function getRenderSink(): RenderSink {
+  return _sink;
+}
+
+export function renderInterceptWarning(m: InterceptMatch): string {
+  const conf = (m.confidence * 100).toFixed(0);
+  const lines = [
+    TOP_BORDER,
+    `│ [${conf}%] ${m.message}`,
+    `│ Why:   ${m.why}`,
+    `│ Scope: ${m.scope_label}`,
+    BOTTOM_BORDER,
+  ];
+  return lines.join("\n");
+}
+
+export function emitMatches(matches: InterceptMatch[] | undefined): void {
+  if (!matches?.length) return;
+  for (const m of matches) _sink(renderInterceptWarning(m));
+}

package/src/ee/scope.test.ts

@@ -0,0 +1,112 @@
+import { promises as fs } from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+// We test the module under test after creating it
+import { buildScope, resetScopeCache, scopeLabel } from "./scope.js";
+
+describe("buildScope", () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    resetScopeCache();
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "scope-test-"));
+  });
+
+  afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true }).catch(() => {});
+  });
+
+  it("returns { kind: 'global' } for a directory without .git", async () => {
+    const scope = await buildScope({ cwd: tmpDir });
+    expect(scope).toEqual({ kind: "global" });
+  });
+
+  it("returns { kind: 'repo', remote } on detached HEAD with remote origin", async () => {
+    const gitDir = path.join(tmpDir, ".git");
+    await fs.mkdir(gitDir, { recursive: true });
+    await fs.writeFile(path.join(gitDir, "HEAD"), "abc123deadbeef\n");
+    await fs.writeFile(path.join(gitDir, "config"), '[remote "origin"]\n\turl = https://github.com/foo/bar.git\n');
+    const scope = await buildScope({ cwd: tmpDir });
+    expect(scope).toEqual({
+      kind: "repo",
+      remote: "https://github.com/foo/bar.git",
+    });
+  });
+
+  it("returns { kind: 'branch', remote, branch } when HEAD points to ref", async () => {
+    const gitDir = path.join(tmpDir, ".git");
+    await fs.mkdir(gitDir, { recursive: true });
+    await fs.writeFile(path.join(gitDir, "HEAD"), "ref: refs/heads/main\n");
+    await fs.writeFile(path.join(gitDir, "config"), '[remote "origin"]\n\turl = https://github.com/foo/bar.git\n');
+    const scope = await buildScope({ cwd: tmpDir });
+    expect(scope).toEqual({
+      kind: "branch",
+      remote: "https://github.com/foo/bar.git",
+      branch: "main",
+    });
+  });
+
+  it("reads .git/HEAD + .git/config via fs (no child_process spawn)", async () => {
+    // Verify the module source does not import child_process
+    const source = await fs.readFile(path.join(process.cwd(), "src/ee/scope.ts"), "utf8");
+    // Check for import/require of child_process (not just mentions in comments)
+    expect(source).not.toMatch(/import.*child_process/);
+    expect(source).not.toMatch(/require.*child_process/);
+    expect(source).not.toMatch(/import.*\bspawn\b/);
+    expect(source).not.toMatch(/import.*\bexec\b/);
+  });
+
+  it("caches: second call returns same object reference", async () => {
+    const gitDir = path.join(tmpDir, ".git");
+    await fs.mkdir(gitDir, { recursive: true });
+    await fs.writeFile(path.join(gitDir, "HEAD"), "ref: refs/heads/dev\n");
+    await fs.writeFile(path.join(gitDir, "config"), '[remote "origin"]\n\turl = https://github.com/a/b.git\n');
+    const first = await buildScope({ cwd: tmpDir });
+    const second = await buildScope({ cwd: tmpDir });
+    expect(first).toBe(second); // same reference
+  });
+
+  it("resetScopeCache forces re-read", async () => {
+    const gitDir = path.join(tmpDir, ".git");
+    await fs.mkdir(gitDir, { recursive: true });
+    await fs.writeFile(path.join(gitDir, "HEAD"), "ref: refs/heads/dev\n");
+    await fs.writeFile(path.join(gitDir, "config"), '[remote "origin"]\n\turl = https://github.com/a/b.git\n');
+    const first = await buildScope({ cwd: tmpDir });
+    resetScopeCache();
+    // Change the branch
+    await fs.writeFile(path.join(gitDir, "HEAD"), "ref: refs/heads/feature\n");
+    const second = await buildScope({ cwd: tmpDir });
+    expect(first).not.toBe(second);
+    expect(second).toEqual({
+      kind: "branch",
+      remote: "https://github.com/a/b.git",
+      branch: "feature",
+    });
+  });
+});
+
+describe("scopeLabel", () => {
+  it("formats global scope", () => {
+    expect(scopeLabel({ kind: "global" })).toBe("global");
+  });
+
+  it("formats ecosystem scope", () => {
+    expect(scopeLabel({ kind: "ecosystem", name: "muonroi" })).toBe("ecosystem:muonroi");
+  });
+
+  it("formats repo scope", () => {
+    expect(scopeLabel({ kind: "repo", remote: "https://github.com/x/y" })).toBe("repo:https://github.com/x/y");
+  });
+
+  it("formats branch scope", () => {
+    expect(
+      scopeLabel({
+        kind: "branch",
+        remote: "https://github.com/x/y",
+        branch: "main",
+      }),
+    ).toBe("branch:https://github.com/x/y#main");
+  });
+});