v0.17.10: can't use `submit_plan` feature in opencode

[ShineBreaker]

GLM-5.1 helped me to find what happened and how to fix.

LINK REMOVED
plannotator-submit-plan-hang.md](https://github.com/user-attachments/files/26795595/plannotator-submit-plan-hang.md

[backnotprop]

Please don't upload files. It's hard to validate them, and I have to create a sandbox to safely read it.

Extracted markdown from sandbox:

Bug: submit_plan Tool Hangs Indefinitely When Browser Cannot Be Opened

Repository: https://github.com/backnotprop/plannotator
Plugin: @plannotator/opencode v0.17.10
Source directory: apps/opencode-plugin
Affected tool: submit_plan

---

Summary

When the submit_plan tool is invoked in an environment where no browser is available (headless, TUI-only, no DISPLAY, or broken xdg-open), the tool hangs indefinitely (default timeout: 96 hours). The tool awaits a decisionPromise that can only be resolved by HTTP POST requests to /api/approve or /api/deny â�� which require the browser-based review UI to be interacted with.

The user sees no feedback, no URL printed to console, and no way to approve/deny the plan from within OpenCode's TUI.

---

Root Cause Analysis

The Blocking Flow

submit_plan execute()
  � startPlannotatorServer()         // starts Bun HTTP server
  � onReady � openBrowser(url)       // tries xdg-open � falls back to tryVscodeIpc()
  � server.waitForDecision()         // returns decisionPromise (NEVER_RESOLVABLE without browser)
  � await decisionPromise            // BLOCKS HERE until /api/approve or /api/deny is POSTed

Key Code Locations (dist/index.js)

Function	Line	Role
DEFAULT_PLAN_TIMEOUT_SECONDS	L47423	345600 (96 hours)
isRemoteSession()	L40775-40784	Checks SSH_TTY/SSH_CONNECTION env vars
getServerPort()	L40785-40794	Returns 0 (random) for local, DEFAULT_REMOTE_PORT for remote
getServerHostname()	L40796-40798	Returns "0.0.0.0" for remote, LOOPBACK_HOST for local
openBrowser()	L41505-41541	Tries xdg-open/open/start, falls back to tryVscodeIpc()
handleServerReady()	L41726-41728	Calls openBrowser(url, { isRemote }) � return value discarded
startPlannotatorServer()	L43220-43565	Creates server, decisionPromise, returns { waitForDecision }
decisionPromise creation	L43260-43262	new Promise((resolve) => { resolveDecision = resolve })
resolveDecision on approve	L43500	resolveDecision({ approved: true, ... })
resolveDecision on deny	L43521	resolveDecision({ approved: false, ... })
Tool execute()	L47668-47746	await server.waitForDecision() � the blocking call
getPlanTimeoutSeconds()	L47488-47499	Reads PLANNOTATOR_PLAN_TIMEOUT_SECONDS env var

Problem 1: openBrowser() Return Value Is Ignored

// L41726-41728
async function handleServerReady(url, isRemote, _port) {
  await openBrowser(url, { isRemote });
  // � Return value (true/false) is completely discarded
}

Even if openBrowser() returns false (all browser-opening methods failed), execution continues to waitForDecision() with no indication that the user cannot access the review UI.

Problem 2: openBrowser() Never Returns false

// L41505-41541
async function openBrowser(url, options) {
  try {
    // ... tries PLANNOTATOR_BROWSER, BROWSER, xdg-open, open, start ...
    return true; // � always returns true if no throw
  } catch {
    return tryVscodeIpc(url); // � fallback also returns true on success
  }
}

xdg-open on Linux often succeeds (exit code 0) even when no browser is available or $DISPLAY is unset â�� it may spawn a background process that immediately exits. The tryVscodeIpc() fallback silently succeeds in some environments without actually opening anything meaningful.

Problem 3: No Console Output of the URL

When the browser fails to open, the URL http://localhost:{port}/ is never printed to console. The user has no way to:

1. Know the server is running
2. Know what port to connect to
3. Manually open the review UI in a browser

The handleServerReady() function just calls openBrowser() and discards everything â�� no console.log() with the URL as a fallback.

Problem 4: 96-Hour Default Timeout Is Effectively Infinite

// L47423
var DEFAULT_PLAN_TIMEOUT_SECONDS = 345600; // 4 days

When the user doesn't set PLANNOTATOR_PLAN_TIMEOUT_SECONDS, the tool blocks for 4 days if no approve/deny is received. In practice, this means the OpenCode session appears completely frozen.

---

Reproduction Steps

Environment

• Linux (Guix System, but reproducible on any Linux without a working browser)
• OpenCode TUI running in a terminal (not VSCode integrated terminal)
• No DISPLAY set, or xdg-open not configured, or no browser installed

Steps

1. Install @plannotator/opencode plugin in opencode.json
2. Start OpenCode TUI
3. Ask the AI agent to create a plan and submit it: e.g. "Plan how to refactor X, then submit_plan"
4. Agent calls submit_plan(plan: "...")
5. Observed: Tool hangs indefinitely. OpenCode TUI is frozen. No URL printed. No feedback.
6. Expected: Either the URL is printed to console for manual access, or the tool returns with a useful error message after a reasonable timeout.

Workaround

Set a short timeout via environment variable:

export PLANNOTATOR_PLAN_TIMEOUT_SECONDS=60  # 60 seconds instead of 96 hours

This at least prevents indefinite hanging, but doesn't solve the core problem � the URL is still not printed, and the user still can't interact with the plan.

---

Suggested Fixes

Fix 1: Print URL to Console When Browser Fails (Minimal, High Impact)

In handleServerReady(), always console.log() the URL as a fallback:

async function handleServerReady(url, isRemote, _port) {
  const opened = await openBrowser(url, { isRemote });
  if (!opened) {
    console.log(
      `[Plannotator] Could not open browser. Review your plan at: ${url}`,
    );
  }
}

Fix 2: Reduce Default Timeout

Change DEFAULT_PLAN_TIMEOUT_SECONDS from 345600 (96 hours) to something reasonable like 600 (10 minutes) or 1800 (30 minutes). If a user needs longer, they can set the env var.

Fix 3: Return Error When Browser Fails and No Alternative Exists

In the tool execute(), check if the browser was successfully opened. If not, and no PLANNOTATOR_PORT was explicitly set (indicating the user set up remote access), return an error:

const browserOpened = await openBrowser(url, { isRemote });
if (!browserOpened && !process.env.PLANNOTATOR_PORT) {
  server.stop();
  return "Error: Could not open browser for plan review. Set PLANNOTATOR_PORT to a specific port and open http://localhost:{port}/ manually.";
}

Fix 4: Integrate with OpenCode TUI (Ideal Solution)

Allow approving/denying plans directly from within OpenCode's TUI, without requiring a browser. This could be a simple yes/no prompt within the terminal.

---

Environment Details

Plugin: @plannotator/opencode@0.17.10
Runtime: Bun
OS: Linux (Guix System, Niri Wayland compositor)
OpenCode: TUI mode (oh-my-openagent v3.17.4)

Related Files (in repo source)

• apps/opencode-plugin/index.ts â�� plugin entry point, tool registration
• packages/server/index.ts â�� startPlannotatorServer(), waitForDecision()
• packages/server/browser.ts â�� openBrowser(), tryVscodeIpc()