Merge pull request #413 from code-yeongyu/fix/monitor-wait-guidance

fix(coding-agent): route waits to the monitor tool — kill the tmux contradiction, teach the bash surface, dedup guidance

Author: code-yeongyu

packages/coding-agent/src/core/extensions/builtin/bash-timeout/timeout.ts

@@ -42,5 +42,5 @@ export function applyBashTimeout<TInput extends BashToolInputLike>(
 
 export function buildBashTimeoutPrompt(defaults: BashTimeoutDefaults): string {
 	const minutes = (seconds: number): string => (seconds % 60 === 0 ? `${seconds / 60} min` : `${seconds}s`);
-	return `\n## Bash Tool Timeout Policy\n\nThe \`bash\` tool enforces timeouts even when you omit the \`timeout\` parameter:\n\n- Default timeout: ${defaults.defaultSeconds}s (${minutes(defaults.defaultSeconds)}). Applied automatically when you do not set \`timeout\`.\n- Recommended maximum timeout: ${defaults.maxSeconds}s (${minutes(defaults.maxSeconds)}). Explicit \`timeout\` values are preserved because different hosts may use different timeout units.\n- For long-running commands (builds, installs, test suites), set an explicit \`timeout\` that fits the workload. Do not assume commands run forever.\n- For commands that legitimately need to run beyond the recommended maximum, run them in the background via tmux or a similar mechanism instead of relying on bash timeout.\n`;
+	return `\n## Bash Tool Timeout Policy\n\nThe \`bash\` tool enforces timeouts even when you omit the \`timeout\` parameter:\n\n- Default timeout: ${defaults.defaultSeconds}s (${minutes(defaults.defaultSeconds)}). Applied automatically when you do not set \`timeout\`.\n- Recommended maximum timeout: ${defaults.maxSeconds}s (${minutes(defaults.maxSeconds)}). Explicit \`timeout\` values are preserved because different hosts may use different timeout units.\n- For long-running commands (builds, installs, test suites), set an explicit \`timeout\` that fits the workload. Do not assume commands run forever.\n- For commands that legitimately need to run beyond the recommended maximum, start them with \`run_in_background: true\` and watch the decisive output with \`monitor\` instead of raising the timeout.\n`;
 }

packages/coding-agent/src/core/extensions/builtin/changes.md

@@ -1,5 +1,17 @@
 # Builtin extensions changes
 
+## bash-timeout: beyond-max routing to run_in_background + monitor (2026-07-28)
+
+- `bash-timeout/timeout.ts` `buildBashTimeoutPrompt()`: the beyond-max bullet no longer teaches
+  "run them in the background via tmux or a similar mechanism" — it now routes to
+  `run_in_background: true` with the decisive output watched via `monitor`. The old advice
+  directly contradicted TERMINAL_PROMPT_SECTION ("do NOT use tmux"), which is appended to the
+  same system prompt immediately after this section (builtin #11 → #12), and contradictions
+  destabilize instruction following more than missing detail.
+- `test/suite/bash-timeout-extension.test.ts`: the "references tmux as the escape hatch" pin is
+  replaced by the new contract (run_in_background + monitor present, tmux absent).
+- Expected merge conflict zones: LOW — fork-owned `timeout.ts` prompt string and its test.
+
 ## Remove the /sessions session-observer HUD (2026-07-26)
 
 - Deleted the `session-observer/` builtin (11 files: `index`, `loader`, `overlay`, `overlay-format`, `scanner`, `text`, `transcript`, `transcript-entries`, `transcript-format`, `types`) and its three vitest suites (`session-observer-picker`, `session-observer-overlay`, `session-observer-scanner`).

packages/coding-agent/src/core/extensions/builtin/terminal/changes.md

@@ -3,6 +3,39 @@
 The persistent-terminal tool suite (`bash` swapped to PTY-backed + `bash_output`,
 `kill_bash`, `bash_input`, `bash_resize`). Backed by `@earendil-works/pi-pty`.
 
+## Wait-discipline routing: bash surface redirect + guidance dedup (2026-07-28)
+
+### What changed
+
+- `tools/bash.ts`: the PTY `bash` tool description now carries the wait redirect — waiting on
+  observable state (a build finishing, a server coming up, a log line) is never a sleep/poll
+  loop; subscribe with the `monitor` tool instead. The bash surface is where a model actually
+  types `sleep 30`, and cross-tool routing in the misused tool's description follows the same
+  pattern as the grep→rg snippet rule (`test/bash-prompt-snippet.test.ts`). The upstream core
+  bash (`src/core/tools/bash.ts`) is deliberately untouched: its toolset has no monitor, and
+  guidance must never name a tool the toolset lacks.
+- `tools/monitor.ts`: promptGuidelines collapsed to the single when-to-use decision rule. The
+  command-shaping sentence duplicated the TERMINAL_PROMPT_SECTION bullet near-verbatim; each
+  aspect is now stated once (decision rule → Tool Guidelines; mechanics → terminal section;
+  redirect → bash schema; long-run routing → bash-timeout policy).
+- `prompt.ts`: the monitor bullet dropped its embedded when-to-use sentence (kept as the monitor
+  tool's guideline) and keeps the subscribe framing plus shaping/filtering/rearm mechanics.
+- `test/prompt-surface-stale-wait-idioms.test.ts`: the consistency gate now enumerates every
+  registered terminal tool surface (description + promptSnippet + promptGuidelines of bash,
+  bash_output, monitor, bash_input, bash_resize, kill_bash) plus the bash-timeout prompt
+  section; new gates assert the bash description routes waits to monitor, and that no
+  agent-facing terminal surface teaches tmux as the backgrounding mechanism — a tmux mention is
+  allowed only when the negation targets tmux itself ("do NOT use tmux"), so "use tmux; never
+  X" cannot slip through.
+- `test/suite/terminal-monitor-notify.test.ts`: the watcher-discipline case now asserts the
+  routing rule at its owning surface (the monitor tool's promptGuidelines) instead of
+  TERMINAL_PROMPT_SECTION, and the noise-control match is wrap-tolerant.
+
+### Expected merge conflict zones on next upstream sync
+
+- LOW: `tools/bash.ts` description string, `tools/monitor.ts` promptGuidelines, `prompt.ts`
+  monitor bullet, gate-test surface list (all fork-owned).
+
 ## Monitor flat schema + subscribe-not-poll prompt (2026-07-27)
 
 ### What changed

packages/coding-agent/src/core/extensions/builtin/terminal/prompt.ts

@@ -14,12 +14,11 @@ manual \`&\` backgrounding — use the built-in session tools:
   \`view: "screen"\`. Completion arrives as a notification carrying the exit code and output
   tail — peeking is for steering, never for waiting.
 - \`monitor({ description, command, filter?, timeout_ms?, persistent? })\` subscribes you to a
-  command: its stdout lines arrive as injected events while you keep working. Any wait on
-  observable state (CI checks, builds, log patterns, deploys) is a monitor, never a foreground
-  sleep/poll loop. Shape the command by notifications needed: exit-on-condition for one
-  completion event; emit-per-occurrence (\`tail -f | grep --line-buffered\`, a polling loop
-  inside the command) for a stream. Filter noise at the command source, stop with \`kill_bash\`,
-  and use \`monitor({ action: "rearm", bash_id })\` only after a wake-budget pause.
+  command: its stdout lines arrive as injected events while you keep working. Shape the command
+  by notifications needed: exit-on-condition for one completion event; emit-per-occurrence
+  (\`tail -f | grep --line-buffered\`, a polling loop inside the command) for a stream. Filter
+  noise at the command source, stop with \`kill_bash\`, and use
+  \`monitor({ action: "rearm", bash_id })\` only after a wake-budget pause.
 - \`bash_input({ bash_id, input, keys, submit })\` sends stdin or named keys (e.g.
   \`["ctrl+c"]\`, \`["enter"]\`) to steer a REPL or interrupt a process.
 - \`bash_resize({ bash_id, cols, rows })\` resizes the PTY so full-screen programs reflow.

packages/coding-agent/src/core/extensions/builtin/terminal/tools/bash.ts

@@ -285,7 +285,7 @@ export function createPtyBashTool(ctx: TerminalToolContext) {
 		name: TERMINAL_BASH_TOOL,
 		label: "bash",
 		description:
-			"Execute a shell command in a persistent PTY-backed session. Set run_in_background:true for long-lived or interactive sessions; steer them with bash_input, snapshot with bash_output, tear down with kill_bash. Foreground timeout is a kill deadline in seconds.",
+			"Execute a shell command in a persistent PTY-backed session. Set run_in_background:true for long-lived or interactive sessions; steer them with bash_input, snapshot with bash_output, tear down with kill_bash. To wait on observable state (a build finishing, a server coming up, a log line), never run sleep or poll loops — subscribe with the monitor tool instead. Foreground timeout is a kill deadline in seconds.",
 		promptSnippet: "Run shell commands; run_in_background:true for long-lived/interactive PTY sessions",
 		promptGuidelines: ["Inspect PI_* environment variables for current model and session details."],
 		parameters: ptyBashSchema,

packages/coding-agent/src/core/extensions/builtin/terminal/tools/monitor.ts

@@ -115,7 +115,6 @@ export function createMonitorTool(ctx: TerminalToolContext) {
 		promptSnippet: "Subscribe to a command's stdout lines as injected events instead of polling",
 		promptGuidelines: [
 			"Waiting on observable state (CI checks, builds, log patterns, deploys) means a monitor, never a foreground sleep/poll loop.",
-			"Shape the command by notifications needed: exit-on-condition for one completion event; emit-per-occurrence (`tail -f | grep --line-buffered`, a polling loop inside the command) for a stream. Filter noise at the source.",
 		],
 		parameters: monitorSchema,
 		renderCall: renderMonitorCall,

packages/coding-agent/test/prompt-surface-stale-wait-idioms.test.ts

@@ -2,12 +2,21 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { describe, expect, it } from "vitest";
+import {
+	buildBashTimeoutPrompt,
+	resolveBashTimeoutDefaults,
+} from "../src/core/extensions/builtin/bash-timeout/timeout.ts";
 import { TERMINAL_PROMPT_SECTION } from "../src/core/extensions/builtin/terminal/prompt.ts";
+import { createPtyBashTool } from "../src/core/extensions/builtin/terminal/tools/bash.ts";
+import { createBashInputTool } from "../src/core/extensions/builtin/terminal/tools/bash-input.ts";
 import {
 	BASH_OUTPUT_WAIT_REMOVED_GUIDANCE,
 	createBashOutputTool,
 } from "../src/core/extensions/builtin/terminal/tools/bash-output.ts";
+import { createBashResizeTool } from "../src/core/extensions/builtin/terminal/tools/bash-resize.ts";
 import type { TerminalToolContext } from "../src/core/extensions/builtin/terminal/tools/context.ts";
+import { createKillBashTool } from "../src/core/extensions/builtin/terminal/tools/kill-bash.ts";
+import { createMonitorTool } from "../src/core/extensions/builtin/terminal/tools/monitor.ts";
 
 /**
  * Consistency gate: no shipped senpi prompt surface may teach the removed
@@ -23,24 +32,60 @@ const CODING_AGENT_ROOT = join(REPO_ROOT, "packages", "coding-agent");
 /** Lines mentioning wait_for are allowed only when they are removal guidance. */
 const GHOST_GUIDANCE_MARKER = /removed|no longer/i;
 
+/** Lines mentioning tmux are allowed only when the negation targets tmux itself. */
+const TMUX_NEGATION = /(do not|don't|never)[^.!?]*\btmux\b/i;
+
 function surfaceLines(name: string, text: string): Array<{ name: string; line: number; text: string }> {
 	return text.split("\n").map((line, index) => ({ name, line: index + 1, text: line }));
 }
 
-function loadSurfaces(): Array<{ name: string; line: number; text: string }> {
-	const stubCtx = {
+function stubTerminalCtx(): TerminalToolContext {
+	return {
 		manager: { get: () => undefined },
 		cwd: process.cwd(),
 		defaultCols: 120,
 		defaultRows: 40,
 		getEnv: () => process.env,
 	} as unknown as TerminalToolContext;
-	const bashOutput = createBashOutputTool(stubCtx);
+}
+
+type PromptSurfaceTool = {
+	name: string;
+	description: string;
+	promptSnippet?: string;
+	promptGuidelines?: readonly string[];
+};
 
+/** description + promptSnippet + promptGuidelines of every registered terminal tool. */
+function terminalToolSurfaces(): Array<{ name: string; line: number; text: string }> {
+	const stubCtx = stubTerminalCtx();
+	const tools: PromptSurfaceTool[] = [
+		createPtyBashTool(stubCtx),
+		createBashOutputTool(stubCtx),
+		createMonitorTool(stubCtx),
+		createBashInputTool(stubCtx),
+		createBashResizeTool(stubCtx),
+		createKillBashTool(stubCtx),
+	];
+	return tools.flatMap((tool) => [
+		...surfaceLines(`${tool.name} description`, tool.description),
+		...surfaceLines(`${tool.name} promptSnippet`, tool.promptSnippet ?? ""),
+		...surfaceLines(`${tool.name} promptGuidelines`, (tool.promptGuidelines ?? []).join("\n")),
+	]);
+}
+
+/** The prompt surfaces the model actually sees (system-prompt sections + tool schemas). */
+function agentFacingSurfaces(): Array<{ name: string; line: number; text: string }> {
 	return [
 		...surfaceLines("terminal/prompt.ts TERMINAL_PROMPT_SECTION", TERMINAL_PROMPT_SECTION),
-		...surfaceLines("bash_output tool description", bashOutput.description),
-		...surfaceLines("bash_output promptSnippet", bashOutput.promptSnippet ?? ""),
+		...surfaceLines("bash-timeout prompt section", buildBashTimeoutPrompt(resolveBashTimeoutDefaults({}))),
+		...terminalToolSurfaces(),
+	];
+}
+
+function loadSurfaces(): Array<{ name: string; line: number; text: string }> {
+	return [
+		...agentFacingSurfaces(),
 		...surfaceLines(
 			"packages/coding-agent/docs/terminal-tools.md",
 			readFileSync(join(CODING_AGENT_ROOT, "docs", "terminal-tools.md"), "utf8"),
@@ -69,15 +114,23 @@ describe("stale wait-idiom consistency gate", () => {
 		expect(TERMINAL_PROMPT_SECTION).not.toContain("wait_for");
 	});
 
+	it("the bash tool surface routes waits to the monitor tool", () => {
+		const bash = createPtyBashTool(stubTerminalCtx());
+		expect(bash.description).toContain("monitor");
+	});
+
+	it("no agent-facing terminal surface teaches tmux as the backgrounding mechanism", () => {
+		const violations = agentFacingSurfaces().filter(
+			({ text }) => /tmux/i.test(text) && !TMUX_NEGATION.test(text),
+		);
+		expect(
+			violations.map(({ name, line, text }) => `${name}:${line}: ${text.trim()}`),
+			"tmux taught as a backgrounding/wait mechanism outside negative guidance",
+		).toEqual([]);
+	});
+
 	it("the bash_output tool surface no longer advertises blocking", () => {
-		const stubCtx = {
-			manager: { get: () => undefined },
-			cwd: process.cwd(),
-			defaultCols: 120,
-			defaultRows: 40,
-			getEnv: () => process.env,
-		} as unknown as TerminalToolContext;
-		const bashOutput = createBashOutputTool(stubCtx);
+		const bashOutput = createBashOutputTool(stubTerminalCtx());
 		expect(bashOutput.description.toLowerCase()).not.toContain("block until");
 		expect(bashOutput.description).not.toContain("wait_for");
 		expect(bashOutput.promptSnippet ?? "").not.toContain("wait_for");

packages/coding-agent/test/suite/bash-timeout-extension.test.ts

@@ -131,9 +131,11 @@ describe("buildBashTimeoutPrompt", () => {
 		expect(prompt).toMatch(/explicit `timeout`/i);
 	});
 
-	it("references tmux as the escape hatch for very long workloads", () => {
+	it("routes beyond-max workloads to background sessions and monitor, not tmux", () => {
 		const prompt = buildBashTimeoutPrompt({ defaultSeconds: 120, maxSeconds: 600 });
 
-		expect(prompt).toContain("tmux");
+		expect(prompt).toContain("run_in_background");
+		expect(prompt).toContain("monitor");
+		expect(prompt).not.toContain("tmux");
 	});
 });

packages/coding-agent/test/suite/terminal-monitor-notify.test.ts

@@ -5,6 +5,8 @@ import {
 } from "../../src/core/extensions/builtin/terminal/monitor-notify.ts";
 import type { MonitorEvent } from "../../src/core/extensions/builtin/terminal/monitor-registry.ts";
 import { TERMINAL_PROMPT_SECTION } from "../../src/core/extensions/builtin/terminal/prompt.ts";
+import type { TerminalToolContext } from "../../src/core/extensions/builtin/terminal/tools/context.ts";
+import { createMonitorTool } from "../../src/core/extensions/builtin/terminal/tools/monitor.ts";
 
 type SentMessage = { readonly content: string; readonly options: { deliverAs?: "steer" | "followUp" } | undefined };
 
@@ -180,11 +182,21 @@ describe("terminal monitor event delivery", () => {
 		}
 	});
 
-	it("teaches watcher discipline in the terminal prompt", () => {
+	it("teaches watcher discipline at the owning terminal surfaces", () => {
 		expect(TERMINAL_PROMPT_SECTION).toContain("monitor");
 		// Discipline is the routing rule (waits are monitors, not poll loops) plus noise control,
-		// not any particular wording — assert the guidance, never a pinned sentence.
-		expect(TERMINAL_PROMPT_SECTION).toMatch(/never a foreground\s+sleep\/poll loop/);
-		expect(TERMINAL_PROMPT_SECTION).toMatch(/Filter noise at the command source/);
+		// not any particular wording — assert each rule at the surface that owns it, never a
+		// pinned sentence: the routing rule ships as the monitor tool's guideline, the noise
+		// rule stays in the terminal section.
+		const stubCtx = {
+			manager: { get: () => undefined },
+			cwd: process.cwd(),
+			defaultCols: 120,
+			defaultRows: 40,
+			getEnv: () => process.env,
+		} as unknown as TerminalToolContext;
+		const guidelines = (createMonitorTool(stubCtx).promptGuidelines ?? []).join("\n");
+		expect(guidelines).toMatch(/never a foreground\s+sleep\/poll loop/);
+		expect(TERMINAL_PROMPT_SECTION).toMatch(/Filter\s+noise at the command source/);
 	});
 });