Nudge never fires in interactive TUI sessions despite E2E passing

[tbrandenburg]

Summary

The plugin works in E2E tests but never sends a nudge in real interactive (TUI) sessions. The root cause is a combination of two issues: lastUserMessage is never populated in TUI sessions, and the two-phase idle fallback requires a second session.idle event that OpenCode never emits.

Root Cause Analysis

1. chat.message hook does not fire for TUI-originated user messages

index.ts registers a chat.message hook to record lastUserMessage:

"chat.message": (messageInput) => {
  handleUserMessage({ sessionID: messageInput.sessionID })
  return Promise.resolve()
},

In practice, when a user types into the TUI and presses Enter, OpenCode does not invoke the plugin's chat.message hook. As a result, lastUserMessage stays at 0 for the entire interactive session.

2. The two-phase fallback requires a second session.idle event that never arrives

Because lastUserMessage === 0, idle-handler.ts falls into the two-phase branch:

} else {
  if (state.lastIdleSeen === 0) {
    state.lastIdleSeen = now   // records first idle
    return                     // waits for a second one
  }
  if (now - state.lastIdleSeen < getIdleThreshold()) return
}

This requires OpenCode to emit a second session.idle event separated by at least IDLE_THRESHOLD (default 5 min) from the first. OpenCode only fires session.idle once per idle transition — no second event ever arrives, so the nudge is never sent.

3. Why E2E passes

The E2E test sets OPENCODE_IDLE_THRESHOLD_MS=0. With a zero threshold, the check now - state.lastIdleSeen < getIdleThreshold() is always false, so the first idle event immediately passes through — regardless of lastUserMessage being unset. The bug is masked entirely by the test's environment override.

Reproduction

1. Build and install the plugin normally (make install && make build-plugin)
2. Start an interactive opencode session (TUI)
3. Send a message and wait — the AI responds and the session goes idle
4. Wait 5+ minutes
5. Observe: no nudge is ever injected

Expected Behaviour

After the configured idle threshold elapses following the AI's response, the plugin injects the continuation prompt.

Proposed Fix

Replace the chat.message hook approach with listening to session.status events (already flowing through the existing event handler). A session.status event with status.type === "running" fires reliably every time the AI starts processing a new user message — making it a correct proxy for "user sent a message":

if (event.type === "session.status" && event.properties.status.type === "running") {
  handleUserMessage({ sessionID: event.properties.sessionID })
}

This removes the dependency on chat.message firing and makes the single-phase path (lastUserMessage > 0) work correctly in all contexts including the TUI.

[tbrandenburg]

/ghar-issue-investigate 4

[github-actions]

Investigation: Nudge never fires in interactive TUI sessions despite E2E passing

Issue: #4 (#4)
Type: BUG
Investigated: 2026-03-31T00:00:00Z

Assessment

Metric	Value	Reasoning
Severity	HIGH	Core plugin functionality (nudge injection) is completely non-functional in TUI sessions
Complexity	LOW	Single file change in index.ts, no architectural changes, isolated modification
Confidence	HIGH	Root cause clearly identified with code evidence; proposed fix uses existing event handler

---

Problem Statement

The plugin's nudge never fires in interactive TUI sessions because handleUserMessage is never called (the chat.message hook doesn't fire for TUI messages), causing lastUserMessage to remain 0. This triggers the two-phase fallback which requires a second session.idle event that never arrives. E2E tests mask this bug by setting OPENCODE_IDLE_THRESHOLD_MS=0.

---

Analysis

Root Cause / Change Rationale

5 Whys chain:

1. WHY: Nudge never fires in TUI sessions
   → BECAUSE: The two-phase fallback in idle-handler.ts:35-40 waits for a second idle event

2. WHY: The two-phase fallback is triggered?
   → BECAUSE: state.lastUserMessage === 0 in idle-handler.ts:34

3. WHY: lastUserMessage is never set?
   → BECAUSE: handleUserMessage() is never called in TUI sessions

4. WHY: handleUserMessage() is never called?
   → BECAUSE: The chat.message hook in index.ts:9-12 does not fire for TUI-originated messages

5. WHY: The chat.message hook doesn't fire in TUI?
   → ROOT CAUSE: OpenCode's TUI does not invoke the plugin's chat.message hook for user-typed messages

Evidence Chain

WHY: Nudge never fires in TUI
↓ BECAUSE: Two-phase fallback waits indefinitely
Evidence: opencode-nudge/src/idle-handler.ts:35-40 - Records lastIdleSeen, returns, waits for second event

↓ BECAUSE: lastUserMessage === 0
Evidence: opencode-nudge/src/idle-handler.ts:34 - Falls to else branch when lastUserMessage > 0 check fails

↓ BECAUSE: handleUserMessage() never called
Evidence: opencode-nudge/src/index.ts:9-12 - Only called from chat.message hook

↓ ROOT CAUSE: chat.message hook doesn't fire for TUI messages
Evidence: opencode-nudge/src/index.ts:9-12 - Hook registration exists but TUI doesn't invoke it

Why E2E Passes

Evidence: opencode-nudge/src/e2e.test.ts:37 - process.env["OPENCODE_IDLE_THRESHOLD_MS"] = "0"

With threshold=0, the check now - state.lastIdleSeen < getIdleThreshold() at line 40 is always false (0 < 0 is false), so the first idle event immediately passes through — regardless of lastUserMessage being unset.

Affected Files

File	Lines	Action	Description
opencode-nudge/opencode-nudge/src/index.ts	1-14	UPDATE	Replace chat.message with session.status listener
opencode-nudge/opencode-nudge/src/idle-handler.test.ts	102-136	UPDATE	Add test for TUI scenario (session.status fires, lastUserMessage set)

Integration Points

• index.ts:8 - event handler already receives all events including session.status
• index.ts:9-12 - chat.message hook (to be removed)
• idle-handler.ts:61-65 - handleUserMessage function (called by new event listener)

---

Implementation Plan

Step 1: Update index.ts to use session.status event

File: opencode-nudge/opencode-nudge/src/index.ts
Lines: 7-13
Action: UPDATE

Current code:

return {
  event: ({ event }) => handleIdleEvent({ event }, input.client),
  "chat.message": (messageInput) => {
    handleUserMessage({ sessionID: messageInput.sessionID })
    return Promise.resolve()
  },
}

Required change:

return {
  event: ({ event }) => {
    if (event.type === "session.status" && event.properties.status.type === "running") {
      handleUserMessage({ sessionID: event.properties.sessionID })
    }
    return handleIdleEvent({ event }, input.client)
  },
}

Why: session.status with status.type === "running" fires reliably when the AI starts processing (after user types and presses Enter), making it a correct proxy for "user sent a message" in all contexts including TUI.

---

Step 2: Add test for TUI scenario

File: opencode-nudge/opencode-nudge/src/idle-handler.test.ts
Action: UPDATE

Add a new test block after line 136 that verifies the session.status event approach works correctly:

describe("session.status event fires for TUI", () => {
  beforeEach(() => sessionStates.clear())

  it("sets lastUserMessage when session.status with running is received", () => {
    // Simulate what happens in TUI: session.status "running" fires instead of chat.message
    handleIdleEvent(
      {
        event: {
          type: "session.status",
          properties: { sessionID: "tui1", status: { type: "running" as const } },
        },
      },
      makeClient() as any
    )
    const state = getOrCreateState("tui1")
    expect(state.lastUserMessage).toBeGreaterThan(0)
    expect(state.lastIdleSeen).toBe(0) // running status should NOT trigger lastIdleSeen
  })

  it("allows single-phase path to work with session.status as proxy for user message", async () => {
    const promptFn = mock(() => Promise.resolve())
    const client = makeClient(promptFn)
    
    // Simulate TUI: session.status "running" fires (user typed message)
    handleIdleEvent(
      {
        event: {
          type: "session.status",
          properties: { sessionID: "tui2", status: { type: "running" as const } },
        },
      },
      client as any
    )
    
    // Backdate to simulate time passing
    const state = getOrCreateState("tui2")
    state.lastUserMessage = Date.now() - getIdleThreshold() - 1000
    
    // Then idle event fires - should trigger continuation on FIRST event (single-phase)
    await handleIdleEvent(idleEvent("tui2"), client as any)
    expect(promptFn).toHaveBeenCalledTimes(1)
  })
})

---

Patterns to Follow

From codebase - mirror these exactly:

// SOURCE: opencode-nudge/src/idle-handler.test.ts:31-33
// Pattern for creating event objects with correct typing
const idleEvent = (sessionID: string) => ({
  event: { type: "session.idle" as const, properties: { sessionID } },
})

// SOURCE: opencode-nudge/src/idle-handler.test.ts:44
// Pattern for typing session.status event
{ type: "session.status", properties: { sessionID: "s1", status: { type: "idle" } } } as any

---

Edge Cases & Risks

Risk/Edge Case	Mitigation
session.status with running might fire multiple times per message	handleUserMessage is idempotent - it just updates lastUserMessage timestamp
Race condition: idle fires before running status	Impossible - running status fires before AI starts, idle fires after AI completes
Event handler order changed	Guard with if (event.type === "session.status") check first

---

Validation

Automated Checks

# Type check
cd opencode-nudge && bun run typecheck

# Run unit tests
cd opencode-nudge && bun test src/idle-handler.test.ts

# Run all tests
cd opencode-nudge && bun test

Manual Verification

1. Build plugin: make build-plugin
2. Install plugin: make install
3. Start interactive opencode session (TUI): opencode
4. Send a message (e.g., "say OK")
5. Wait for AI response to complete
6. Wait 5+ minutes past the AI response
7. Verify: continuation prompt appears as injected user message

---

Scope Boundaries

IN SCOPE:

• Updating index.ts to use session.status event
• Adding unit tests for the new behavior
• Ensuring existing tests still pass

OUT OF SCOPE (do not touch):

• idle-handler.ts logic (correct, no changes needed)
• throttle.ts (unrelated to bug)
• E2E test environment variable (should remain as-is for now)
• Documentation updates (defer to separate PR)

---

Metadata

• Investigated by: GHAR
• Timestamp: 2026-03-31T00:00:00Z
• Artifact: .ghar/issues/issue-4.md

[github-actions]

🤖 OpenCode Execution Complete

Command: /ghar-issue-investigate
Run ID: 23819570703
Status: ✅ Completed

Results

Now let me explore the codebase to verify the findings and understand the implementation.
Now I have all the information needed. Let me create the artifact.

Investigation Complete

Issue: #4 - Nudge never fires in interactive TUI sessions despite E2E passing
Type: BUG

Assessment

Metric	Value	Reasoning
Severity	HIGH	Core functionality completely non-functional in TUI sessions
Complexity	LOW	Single file change in index.ts, no architectural changes
Confidence	HIGH	Root cause clearly identified with code evidence

Key Findings

• Root Cause: chat.message hook doesn't fire for TUI messages, so lastUserMessage stays 0, triggering two-phase fallback that requires a second session.idle event that never arrives
• Files Affected: 2 files
• Estimated Changes: ~5 lines in index.ts, new test block in idle-handler.test.ts

Files to Modify

File	Action
opencode-nudge/opencode-nudge/src/index.ts	UPDATE
opencode-nudge/opencode-nudge/src/idle-handler.test.ts	UPDATE

GitHub

Posted to issue: #4 (comment)

[github-actions]

🕰️ This issue has been inactive for over 3 days.

@tbrandenburg - Could you provide an update on this issue?

If this issue is resolved or no longer relevant, please consider closing it.