[BUG] Incorrect Background Bash Process Tracking

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

<h1>🐞 Bug: Completed Background Bash Processes Reported as “Running”</h1>
<h2>🧩 Summary</h2>
<p>Claude Code continues reporting background Bash processes as <strong>“running”</strong> even after they’ve completed successfully, causing persistent false reminders about non-existent zombie processes.</p>
<hr>
<h2>🧠 Environment</h2>

Key | Value
-- | --
Claude Code Version | Latest (as of 2025-10-15)
OS | macOS (Darwin 25.1.0)
Shell | zsh
Node Version | 20.x

<p><strong>Example (Unsafe):</strong></p>
<pre><code class="language-bash">ps aux | grep -E "npm|node" | awk '{print $2}' | xargs -r kill -9
killall -9 node
</code></pre>
<hr>
<h2>🔍 Root Cause (Hypothesis)</h2>
<p>Issue likely resides in <strong>background process lifecycle synchronization</strong>:</p>
<ol>
<li>
<p>Process completion isn’t reflected in the internal tracking system</p>
</li>
<li>
<p><code inline="">BashOutput</code> fetches correct status, but tracking data remains stale</p>
</li>
<li>
<p>System reminders rely on outdated “running” status instead of verifying process existence</p>
</li>
</ol>
<h3>Possible Code Areas</h3>
<ul>
<li>
<p>Background process lifecycle management</p>
</li>
<li>
<p>Status synchronization logic</p>
</li>
<li>
<p>Reminder generation module</p>
</li>
</ul>
<hr>
<h2>🛠️ Suggested Fixes</h2>
<ul>
<li>
<p><strong>Sync Status:</strong> Update internal tracking when <code inline="">BashOutput</code> detects completion</p>
</li>
<li>
<p><strong>Verify Processes:</strong> Periodically confirm that tracked processes still exist via PID checks</p>
</li>
<li>
<p><strong>Auto Cleanup:</strong> Remove completed processes after a defined grace period</p>
</li>
<li>
<p><strong>Stop Reminders:</strong> Suppress notifications for completed or non-existent processes</p>
</li>
<li>
<p><strong>Expose Cleanup API:</strong> Provide a command or endpoint to clear stale process records</p>
</li>
</ul>
<hr>
<h2>🧪 Test Case</h2>
<pre><code class="language-typescript">describe('Background Bash Process Tracking', () =&gt; {
it('should mark a background process as completed after it exits', async () =&gt; {
const result = await Bash({ command: "sleep 1 &amp;&amp; echo 'done'", run_in_background: true });
const bashId = result.bash_id;

await new Promise(r =&gt; setTimeout(r, 2000));
const output = await BashOutput({ bash_id: bashId });
expect(output.status).toBe('completed');

await new Promise(r =&gt; setTimeout(r, 3600000)); // simulate 1 hour later

// Expected: No reminders for completed process
// Actual: System reminders persist claiming "running"
});
});
</code></pre>
<hr>
<h2>🧰 Additional Info</h2>
<h3><strong>Safe User Verification</strong></h3>
<p>Users can confirm no real processes are running with:</p>
<pre><code class="language-bash">ps aux | grep "your-process-name" | grep -v grep
</code></pre>
<p>If no output appears, the warnings can be safely ignored.</p>
<h3><strong>Fix Priority</strong></h3>
<p><strong>High</strong> — significantly impacts developer trust, workflow efficiency, and UX.</p>
<hr>
<h2>👤 Reporter</h2>
<p><strong>Name:</strong> Jacob<br>
<strong>Date Reported:</strong> 2025-10-15<br>
<strong>Attachments:</strong></p>
<ul>
<li>
<p>Session logs showing false “running” reminders</p>
</li>
<li>
<p><code inline="">ps aux</code> output (no matching processes)</p>
</li>
<li>
<p><code inline="">BashOutput</code> XML confirming completion</p>
</li>
</ul>
<hr>

What Should Happen?

When a background Bash process completes:

1. Its status should update to completed
2. System reminders should stop appearing
3. The process should be removed from the active tracking list

Error Messages/Logs

Steps to Reproduce

Launch a long-running background Bash command using run_in_background: true:

1. Wait for the process to complete (may take 1-2 minutes)

1. Use BashOutput to check the process status:

``typescript
BashOutput({ bash_id: "abc123" })
``

1. Observe that BashOutput correctly reports:

``
<status>completed</status>
<exit_code>0</exit_code>
<timestamp>2025-10-14T18:21:55.370Z</timestamp>
``

1. Continue working in the session (hours or even days later)

1. Observe that Claude Code STILL shows system reminders claiming the process is "running"

Claude Model

Sonnet (default)

Is this a regression?

I don't know

Last Working Version

_No response_

Claude Code Version

2.0.15

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Terminal.app (macOS)

Additional Information

_No response_