chore(visibility): surface previously-silent failure paths via CODEBASE_DEBUG=1

Three places swallowed errors with empty catches, plus a typed mock
factory for tests so the ToolContext interface can't drift past them
unnoticed.

- agent.ts diagnostics after edit: was silent, now stderr under
  CODEBASE_DEBUG=1. Buried a real case where a checker was hanging
  on a generated file and edits looked sluggish.
- hooks/manager.ts async hook failures: same shape — user-configured
  hooks that throw on every dispatch are otherwise invisible.
- glue/client.ts parseGlueRef: when GLUE_FAST_MODEL or GLUE_SMART_MODEL
  references a model id that can't be resolved, we fall back to the
  parent. Useful behaviour, but the silent fallback meant typos went
  unnoticed and 'smart' calls were quietly using the wrong tier.
- New makeMockToolContext factory in tools/__test__/ uses real stores
  (cheap, in-memory) instead of {} as any. Tests now fail-closed when
  a new required field is added to ToolContext.

Author: halfaipg

src/agent/agent.ts

@@ -217,8 +217,16 @@ export function createAgent(opts: CreateAgentOptions = {}): AgentBundle {
 							timestamp: Date.now(),
 						});
 					})
-					.catch(() => {
-						// Diagnostics failures are non-fatal — surface nothing.
+					.catch((err) => {
+						// Diagnostics failures are non-fatal — surface only when the
+						// user opted into debug. Silent before; that buried a real
+						// bug where a checker hung and the user thought the tool
+						// itself was slow.
+						if (process.env.CODEBASE_DEBUG === "1") {
+							process.stderr.write(
+								`[diagnostics] ${absPath}: ${err instanceof Error ? err.message : String(err)}\n`,
+							);
+						}
 					});
 			}
 			return undefined;

src/glue/client.ts

@@ -92,5 +92,15 @@ export function parseGlueRef(ref: string, fallback: Model<string>): Model<string
 
 	const [maybeProvider, maybeId] = trimmed.includes(":") ? trimmed.split(":", 2) : [fallback.provider, trimmed];
 	const found = getModel(maybeProvider as KnownProvider, maybeId as never);
-	return (found as Model<string> | undefined) ?? fallback;
+	if (found) return found as Model<string>;
+	// Lookup miss — typo or unknown model. Falling back is correct, but
+	// silent fallback meant users who set GLUE_SMART_MODEL=foo-typo
+	// thought they were getting their smart model and were actually
+	// getting the parent. Make it visible under CODEBASE_DEBUG=1.
+	if (process.env.CODEBASE_DEBUG === "1") {
+		process.stderr.write(
+			`[glue] no model matched "${trimmed}" — falling back to ${fallback.provider}/${fallback.id}\n`,
+		);
+	}
+	return fallback;
 }

src/hooks/manager.ts

@@ -65,8 +65,16 @@ export class HookManager {
 
 		for (const config of matching) {
 			if (config.async) {
-				runHook(config, context, signal).catch(() => {
-					// fire-and-forget; nothing to do on failure
+				runHook(config, context, signal).catch((err) => {
+					// async hooks fire-and-forget by design, but a hook that's
+					// silently throwing on every event will mystify the user
+					// who configured it. Surface to stderr under CODEBASE_DEBUG
+					// so it's visible when someone is actually looking.
+					if (process.env.CODEBASE_DEBUG === "1") {
+						process.stderr.write(
+							`[hook async event=${event}] ${err instanceof Error ? err.message : String(err)}\n`,
+						);
+					}
 				});
 				ranCount++;
 				continue;

src/tools/__test__/mock-tool-context.ts

@@ -0,0 +1,33 @@
+/**
+ * Typed factory for a ToolContext suitable for unit tests. Uses real
+ * instances of the in-memory stores (they're cheap to construct) so
+ * tests catch interface-shape drift the moment a field is added to
+ * ToolContext — previously this was `{} as any` for every field, which
+ * meant adding a new required member to ToolContext compiled green
+ * while every test was secretly missing it.
+ */
+
+import { MemoryStore } from "../../memory/store.js";
+import { PlanModeStore } from "../../plan/store.js";
+import { UserQueryStore } from "../../user-queries/store.js";
+import { FileStateCache } from "../file-state-cache.js";
+import { TaskStore } from "../task-store.js";
+import type { ToolContext } from "../types.js";
+
+export function makeMockToolContext(cwd: string): ToolContext {
+	return {
+		cwd,
+		fileStateCache: new FileStateCache(),
+		tasks: new TaskStore(),
+		userQueries: new UserQueryStore(),
+		planMode: new PlanModeStore(),
+		memory: new MemoryStore({ cwd }),
+		// spawnSubagent is the only field a test can't supply a real
+		// implementation for (it depends on the live agent factory).
+		// We throw to make the boundary explicit: any test that calls a
+		// subagent-spawning tool needs to provide its own stub.
+		spawnSubagent: () => {
+			throw new Error("mock-tool-context: spawnSubagent not stubbed — provide one in the test if you need it");
+		},
+	};
+}

src/tools/config.test.ts

@@ -2,26 +2,10 @@ import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { makeMockToolContext } from "./__test__/mock-tool-context.js";
 import { createConfig } from "./config.js";
-import type { ToolContext } from "./types.js";
 
-function makeCtx(cwd: string): ToolContext {
-	return {
-		cwd,
-		// biome-ignore lint/suspicious/noExplicitAny: minimal stub for tool context
-		fileStateCache: {} as any,
-		// biome-ignore lint/suspicious/noExplicitAny: minimal stub
-		tasks: {} as any,
-		// biome-ignore lint/suspicious/noExplicitAny: minimal stub
-		userQueries: {} as any,
-		// biome-ignore lint/suspicious/noExplicitAny: minimal stub
-		planMode: {} as any,
-		// biome-ignore lint/suspicious/noExplicitAny: minimal stub
-		memory: {} as any,
-		// biome-ignore lint/suspicious/noExplicitAny: minimal stub
-		spawnSubagent: (() => {}) as any,
-	};
-}
+const makeCtx = makeMockToolContext;
 
 describe("config tool", () => {
 	let cwd: string;