feat(tui): pin spawn effort via OCP_TUI_EFFORT (default low) (#156)

* feat(tui): pin spawn effort via OCP_TUI_EFFORT (default low)

buildTuiCmd never passed --effort, so the pane's claude inherited a
HOME-dependent effortLevel: real-home mode inherits the operator's
~/.claude/settings.json (high/xhigh on typical operator hosts),
env-token scratch mode inherits claude's built-in default — proxied-turn
latency silently depended on which HOME mode resolveTuiHome() picked and
on an unrelated operator setting.

Pass --effort explicitly, from new env var OCP_TUI_EFFORT (default
"low"; allowlist low|medium|high|xhigh|max per `claude --help` 2.1.207;
"inherit" restores the pre-flag argv byte-for-byte; an invalid value
warns and falls back to "low" so a typo can never reach the pane argv).

Not endpoint-touching: no server.mjs change, no wire-level change — the
flag rides the existing interactive spawn (ADR 0007). Billing-pool
safety verified per the docs/plans/2026-07-13-tui-latency banner
protocol: startup banner stays "Claude Max" with "low effort".

Measured through a test OCP instance (:3979, TUI mode, real-home,
claude-sonnet-4-6, n=5+5, same ~1850-token prompt as floor.sh):

  before: median 11.30s  range 9.05-12.38s (spread 3.32s)  banner: high effort - Claude Max
  after:  median  9.55s  range 9.27-9.77s  (spread 0.50s)  banner: low effort - Claude Max
  OCP_TUI_EFFORT=inherit: banner back to "high effort" (pre-flag behavior restored)

README: new row in the Environment Variables table (release_kit
new_feature_doc_expectations: new env var -> README table). Tests: 4 new
buildTuiCmd cases (default, explicit level, inherit, invalid fallback);
suite 267 passed / 0 failed.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VqgWJcjxrjjL9L9SkpZyXR

* docs(readme): review nit — 'pre-v3.22' → 'pre-flag' (next version not fixed yet)

Reviewer nit from the Iron Rule 10 independent review of PR #156.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VqgWJcjxrjjL9L9SkpZyXR

---------

Co-authored-by: dtzp555 <dtzp555@gmail.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

test-features.mjs

@@ -1795,6 +1795,65 @@ test("buildTuiCmd shq-escapes a token containing shell metacharacters (no inject
   }
 });
 
+// OCP_TUI_EFFORT (TUI latency, docs/plans/2026-07-13-tui-latency): the pane's claude
+// must get an EXPLICIT --effort so its effort never depends on which HOME mode
+// resolveTuiHome() picked (real-home inherits the operator's settings.json effortLevel;
+// env-token scratch inherits claude's built-in default).
+test("buildTuiCmd passes --effort low by default (OCP_TUI_EFFORT unset)", () => {
+  const save = process.env.OCP_TUI_EFFORT;
+  try {
+    delete process.env.OCP_TUI_EFFORT;
+    const cmd = buildTuiCmd("/usr/bin/claude", "m", "sid-eff1", "/home/u", "cli");
+    assert.ok(cmd.includes("--effort low"), "default must pin --effort low");
+  } finally {
+    if (save === undefined) delete process.env.OCP_TUI_EFFORT;
+    else process.env.OCP_TUI_EFFORT = save;
+  }
+});
+
+test("buildTuiCmd honors an explicit OCP_TUI_EFFORT level (case/space-normalized)", () => {
+  const save = process.env.OCP_TUI_EFFORT;
+  try {
+    process.env.OCP_TUI_EFFORT = " XHigh ";
+    const cmd = buildTuiCmd("/usr/bin/claude", "m", "sid-eff2", "/home/u", "cli");
+    assert.ok(cmd.includes("--effort xhigh"), "explicit level must be passed, normalized");
+    assert.ok(!cmd.includes("--effort low"), "default must not also appear");
+  } finally {
+    if (save === undefined) delete process.env.OCP_TUI_EFFORT;
+    else process.env.OCP_TUI_EFFORT = save;
+  }
+});
+
+test("buildTuiCmd OCP_TUI_EFFORT=inherit omits --effort entirely (pre-flag argv)", () => {
+  const save = process.env.OCP_TUI_EFFORT;
+  try {
+    process.env.OCP_TUI_EFFORT = "inherit";
+    const cmd = buildTuiCmd("/usr/bin/claude", "m", "sid-eff3", "/home/u", "cli");
+    assert.ok(!/--effort/.test(cmd), "inherit must not add --effort");
+  } finally {
+    if (save === undefined) delete process.env.OCP_TUI_EFFORT;
+    else process.env.OCP_TUI_EFFORT = save;
+  }
+});
+
+test("buildTuiCmd falls back to --effort low on an invalid OCP_TUI_EFFORT (never reaches argv)", () => {
+  const save = process.env.OCP_TUI_EFFORT;
+  const savedErr = console.error;
+  try {
+    process.env.OCP_TUI_EFFORT = "ludicrous'; rm -rf /;'";
+    let warned = "";
+    console.error = (...a) => { warned = a.join(" "); };
+    const cmd = buildTuiCmd("/usr/bin/claude", "m", "sid-eff4", "/home/u", "cli");
+    assert.ok(cmd.includes("--effort low"), "invalid value must fall back to low");
+    assert.ok(!cmd.includes("ludicrous"), "invalid raw value must NOT reach the shell string");
+    assert.ok(/invalid OCP_TUI_EFFORT/.test(warned), "must log a warning");
+  } finally {
+    console.error = savedErr;
+    if (save === undefined) delete process.env.OCP_TUI_EFFORT;
+    else process.env.OCP_TUI_EFFORT = save;
+  }
+});
+
 test("buildTuiCmd OCP_TUI_FULL_TOOLS=1 grants -p-equivalent tool surface (single-user opt-in)", () => {
   const save = { ...process.env };
   const restore = () => {