feat: gate verbose logs behind ZCODE_ACP_DEBUG (quiet by default)

[william0wang]

Summary

Introduces a two-level logger so the bridge is quiet by default — only perceivable failures appear in Zed.log. Verbose diagnostics are gated behind ZCODE_ACP_DEBUG=1 and emitted only when explicitly enabled.

This keeps Zed.log clean for stable daily use while preserving the rich diagnostics that were essential for diagnosing the recent compact, mode, and permission bugs (just opt in with the env var).

Design

Function	Default	ZCODE_ACP_DEBUG=1	Purpose
`warn(msg)`	emitted	emitted	Perceivable failures (always visible)
`log(msg)`	suppressed	emitted	Diagnostic detail (opt-in)

• Default behavior is now quiet — a stable bridge doesn't spam Zed.log.
• `warn()` always emits: backend pipe errors, fatal exit, `turn.failed`, command/permission failures, lock/preempt timeouts, model switch failures.
• `log()` is gated: event flow (`turn.started`/`completed`), probe loops, reannounce dedup, success markers (`→ ok`), startup info, config-read fallbacks (with graceful degradation).
• `isDebug()` reads `process.env.ZCODE_ACP_DEBUG` at call time (not module load) so tests can flip it without re-importing.

Migration (21 `log()` → `warn()`)

Key failures migrated so they stay visible in the default quiet mode. Categorization rule: user-perceivable failures → `warn`; pure flow tracing / graceful-fallback paths → `log`.

• `backend/client.ts` — stdin error, reader exited, 4× dropped (pipe broken)
• `index.ts` — fatal (process crash)
• `handlers/server-requests.ts` — unhandled request, permission timeout/failed/cancelled, AskUserQuestion no-valid-questions / skip-cancel / elicitation-declined
• `handlers/extensions.ts` — compact/goal lock-wait timeout (split the success/timeout ternary into separate log/warn)
• `handlers/session.ts` — `emitModeIfChanged` failure, preempt timeout
• `handlers/slash.ts` — slash command failure
• `translators/event-translator.ts` — `turn.failed`
• `config/runtime-model.ts` — model switch failed

The remaining 61 `log()` calls are intentional: `→ ok` success markers, `[event]`/`[probe]`/`[preempt]` tracing, reannounce dedup, startup notices, and catch blocks with graceful fallbacks (model-cache session/read, tasks-index sync).

Verification

• `pnpm build` — clean
• `pnpm test` — 94/94 passing (4 new tests in `tests/utils.test.ts`: default silenced, `DEBUG=1` emits, `warn` always emits, `DEBUG=0` stays silenced)
• `prettier` applied to all changed files
• All `⚠`-marked log lines verified migrated to `warn` (grep confirmed 0 remaining)

Files

• `src/utils.ts` — `isDebug()` + `warn()` (the gating infrastructure)
• 8 handler/config/backend files — migration of 21 key failures to `warn`
• `tests/utils.test.ts` — new, 4 gating tests
• `README.md` / `README.zh-CN.md` — `ZCODE_ACP_DEBUG` documented in the env-var table

[gemini-code-assist]

Code Review

This pull request introduces a new environment variable ZCODE_ACP_DEBUG to toggle verbose diagnostic logging, updating various log statements across the codebase to use a newly introduced warn function for always-emitted warnings. Unit tests are added to verify the logging behavior, and documentation is updated accordingly. The review feedback suggests using optional chaining on requestedSchema in src/handlers/server-requests.ts to prevent potential runtime errors, and correcting a minor Markdown formatting issue in README.zh-CN.md.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

To prevent potential runtime errors, it is safer to use optional chaining when accessing properties on requestedSchema. If requestedSchema or properties is undefined, calling Object.keys directly will throw a TypeError.

Suggested change

	log(
	` ⟳ AskUserQuestion forwarding elicitation/create (form, ${Object.keys(formParams.requestedSchema.properties).length} fields)`,
	);
	log(
	` ⟳ AskUserQuestion forwarding elicitation/create (form, ${Object.keys(formParams.requestedSchema?.properties ?? {}).length} fields)`,
	);

[gemini-code-assist]

在 README.zh-CN.md 中，_（未设置） 缺少了结尾的下划线 _，导致 Markdown 格式不一致。建议将其修改为 _（未设置）_ 以保持与第 62 行 _（自动发现）_ 一致的斜体格式。

Suggested change

	| `ZCODE_ACP_DEBUG` | _（未设置）| 设为 `1` 可开启详细诊断日志（事件流、探测循环、状态更新）。默认安静——只输出警告类日志（后端管道错误、命令/权限失败、锁等待超时）。诊断桥接问题时开启；日志出现在 `Zed.log` 中，前缀为 `[zcode-acp]`。 |
	| `ZCODE_ACP_DEBUG` | _（未设置）_ | 设为 `1` 可开启详细诊断日志（事件流、探测循环、状态更新）。默认安静——只输出警告类日志（后端管道错误、命令/权限失败、锁等待超时）。诊断桥接问题时开启；日志出现在 `Zed.log` 中，前缀为 `[zcode-acp]`。 |