Skip to content

A self-improving RLM agent for coding workflows and long-running autonomous tasks.

Rust

feat(coding-agent): hold goal/autonomous continuations while background bash() handles run (#2465)

Seth Kartenb08f08efad68
diff --git a/packages/coding-agent/.changes/continuation-background-bash-gate.md b/packages/coding-agent/.changes/continuation-background-bash-gate.md
new file mode 100644
index 0000000000..f2e8ff4b6e
--- /dev/null
+++ b/packages/coding-agent/.changes/continuation-background-bash-gate.md
@@ -0,0 +1 @@
+- Timer-driven goal and autonomous continuations now pause while background `bash()` handles are still running instead of re-prompting the waiting agent: the last handle settling is the wake-up (its completion notice is delivered first, then the held continuation resumes behind it without spending continuation budget while it waits), and the kernel now notifies the host when its live background handles settle or the kernel tears down.
diff --git a/packages/coding-agent/docs/long-running-agents.md b/packages/coding-agent/docs/long-running-agents.md
index e06729f2e5..8950add85e 100644
--- a/packages/coding-agent/docs/long-running-agents.md
+++ b/packages/coding-agent/docs/long-running-agents.md
@@ -238,12 +238,19 @@ continuations instead of re-prompting the waiting parent: child replies and
exit notices are the real wake-up signals, so idle status-check turns no
longer burn continuation budget. The held continuation is delivered once the
descendants settle, mirroring how goal continuations wait for subagent work.
+Background `bash()` handles get the same treatment: while a handle is still
+running, timer-driven goal and autonomous continuations pause without
+spending budget. The last handle settling is the wake-up: its "Background
+command finished" notice, when one is owed, is delivered first, then the held
+continuation resumes behind it.
A slow keep-alive valve still fires one continuation per window of continuous
subagent activity so the parent can inspect and unblock hung children (for
example, stopped processes); the default window is 25 minutes and
`--subagent-keep-alive-ms 0` disables it. Keep the window below any
configured wall-clock budget so the valve fires before `--timeout-ms` caps
-the run.
+the run. A background `bash()` handle that never exits holds the pause
+indefinitely by design — the handle settling, not a timer, is the wake-up —
+and a user prompt always wakes the session immediately.
Autonomous mode supports limits for continuations, assistant turns, tokens, and wall-clock duration. Gate commands run before the session may finish; a failed gate returns its bounded output to the agent for another attempt. Prime Agent avoids rerunning the same failed gate when the workspace has not changed.
diff --git a/packages/coding-agent/docs/rlm.md b/packages/coding-agent/docs/rlm.md
index 205ec990f0..80c48bc4b6 100644
--- a/packages/coding-agent/docs/rlm.md
+++ b/packages/coding-agent/docs/rlm.md
@@ -55,7 +55,7 @@ checks = bash("npm test")
checks.pid
```
-When an unawaited handle's process group finishes, Prime Agent sends a "Background command finished" notice with its PID and foreground exit code. A busy agent receives it as steering at the next safe turn boundary, without interrupting a running tool. An idle agent resumes to handle it. `await handle` and `handle.poll()` still return the foreground result before shell background jobs finish. The kernel stays resident until the process group is reaped, including for handles awaited in their creating cell. The message asks the agent to inspect the saved handle with `poll()`, `output()`, or `tail()` and continue the task. `await bash(...)` stays synchronous from the agent's perspective and does not send a second notice.
+When an unawaited handle's process group finishes, Prime Agent sends a "Background command finished" notice with its PID and foreground exit code. A busy agent receives it as steering at the next safe turn boundary, without interrupting a running tool. An idle agent resumes to handle it. While the handle runs, timer-driven goal and autonomous continuations pause instead of re-prompting the waiting agent; the last handle settling is the wake-up — its completion notice, when one is owed, is delivered first, then the held continuation resumes behind it. `await handle` and `handle.poll()` still return the foreground result before shell background jobs finish. The kernel stays resident until the process group is reaped, including for handles awaited in their creating cell. The message asks the agent to inspect the saved handle with `poll()`, `output()`, or `tail()` and continue the task. `await bash(...)` stays synchronous from the agent's perspective and does not send a second notice.
Reading the finished result withdraws the notice. Any read from a live cell counts -- `await handle`, `handle.poll()`, `handle.output()`, `handle.tail()` -- so a notice that is still queued is dropped and a notice that was not sent yet is never sent. Reads that no cell receives do not count: a detached watcher polling the handle between turns leaves the notice in place, because that notice is the only wake-up an idle session gets, and an `asyncio.as_completed` or `create_task` wrapper that resolves with no live cell waiting for it does not count either. A notice the agent already received is never retracted.
diff --git a/packages/coding-agent/src/core/agent-session.ts b/packages/coding-agent/src/core/agent-session.ts
index 712b0cf32e..be9a0d1a9c 100644
--- a/packages/coding-agent/src/core/agent-session.ts
+++ b/packages/coding-agent/src/core/agent-session.ts
@@ -1430,9 +1430,10 @@ export class AgentSession {
private _autonomousState: AutonomousRuntimeState;
private _autonomousContinuationSuppressionDepth = 0;
private _autonomousContinuationSuppressedMessages = new WeakSet<AgentMessage>();
- // Held autonomous continuation owed while descendant work runs; mirrors
- // _goalContinuationAwaitsRlmWork. Child replies and exit notices are the
- // real wake-up signals, so timer-driven continuations pause instead of
+ // Held autonomous continuation owed while descendant or background bash
+ // work runs; mirrors _goalContinuationAwaitsRlmWork. Child replies, exit
+ // notices, and background bash completion follow-ups are the real
+ // wake-up signals, so timer-driven continuations pause instead of
// re-prompting a waiting parent (and pause without consuming budget).
private _autonomousContinuationAwaitsRlmWork = false;
private _autonomousSubagentKeepAliveTimer: ReturnType<typeof setTimeout> | undefined = undefined;
@@ -2542,7 +2543,14 @@ export class AgentSession {
private _maybeResumeGoalContinuationAfterRlmWork(): void {
if (!this._goalContinuationAwaitsRlmWork) return;
- if (this._disposed || this._disposing || this._hasUnsettledRlmQuiescenceWork()) return;
+ if (
+ this._disposed ||
+ this._disposing ||
+ this._hasUnsettledRlmQuiescenceWork() ||
+ this._hasLiveBackgroundBashHandles()
+ ) {
+ return;
+ }
if (this._goalState.status !== "active" || !this._goalState.objective) {
this._goalContinuationAwaitsRlmWork = false;
return;
@@ -2576,12 +2584,13 @@ export class AgentSession {
}
/**
- * Hold the timer-driven autonomous continuation while descendant work is
- * unsettled, mirroring the goal gate: delegating and ending the turn is
- * correct behavior, and child replies and exit notices are the real
- * wake-up signals. The owed continuation is delivered when descendants
- * settle without consuming the continuation budget while it waits. An
- * active goal holds its own continuation, so the held continuation is
+ * Hold the timer-driven autonomous continuation while descendant or
+ * background bash work is unsettled, mirroring the goal gate: delegating
+ * and ending the turn is correct behavior, and child replies, exit
+ * notices, and background bash completion follow-ups are the real
+ * wake-up signals. The owed continuation is delivered when the pending
+ * work settles without consuming the continuation budget while it waits.
+ * An active goal holds its own continuation, so the held continuation is
* not double-queued behind it.
*/
private _holdAutonomousContinuationForRlmWork(message: AssistantMessage): boolean {
@@ -2595,7 +2604,7 @@ export class AgentSession {
// The run is over: hold nothing so the hook can apply the limit.
return false;
}
- if (!this._hasUnsettledRlmQuiescenceWork()) {
+ if (!this._hasUnsettledRlmQuiescenceWork() && !this._hasLiveBackgroundBashHandles()) {
return false;
}
// An active goal's own continuation gate owns the wake-up discipline;
@@ -2614,10 +2623,27 @@ export class AgentSession {
return this._goalState.status === "active" && !!this._goalState.objective;
}
+ /**
+ * True while the session's kernel still runs background bash() handles.
+ * The kernel's bash-activity tracking (the same state that powers the
+ * bash-done completion follow-ups) is the liveness surface, so a live
+ * handle's completion notice is the wake-up a held continuation waits for.
+ */
+ private _hasLiveBackgroundBashHandles(): boolean {
+ return this._ipythonKernelProvisioner?.manager?.hasBackgroundWork === true;
+ }
+
/** Deliver the owed continuation once descendant work settles. */
private _maybeResumeAutonomousContinuationAfterRlmWork(): void {
if (!this._autonomousContinuationAwaitsRlmWork) return;
- if (this._disposed || this._disposing || this._hasUnsettledRlmQuiescenceWork()) return;
+ if (
+ this._disposed ||
+ this._disposing ||
+ this._hasUnsettledRlmQuiescenceWork() ||
+ this._hasLiveBackgroundBashHandles()
+ ) {
+ return;
+ }
if (!this._autonomousState.enabled || this._goalOwnsContinuationWakeup()) {
this._clearAutonomousContinuationAwait();
return;
@@ -2767,9 +2793,9 @@ export class AgentSession {
private _fireAutonomousSubagentKeepAlive(): void {
if (!this._autonomousContinuationAwaitsRlmWork) return;
if (this._disposed || this._disposing) return;
- if (!this._hasUnsettledRlmQuiescenceWork()) {
- // Descendants settled while the keep-alive was pending; the normal
- // resume path owns delivery.
+ if (!this._hasUnsettledRlmQuiescenceWork() && !this._hasLiveBackgroundBashHandles()) {
+ // Descendants and background handles settled while the keep-alive
+ // was pending; the normal resume path owns delivery.
this._maybeResumeAutonomousContinuationAfterRlmWork();
return;
}
@@ -2783,6 +2809,14 @@ export class AgentSession {
this._armAutonomousSubagentKeepAlive();
return;
}
+ if (!this._hasUnsettledRlmQuiescenceWork()) {
+ // Only background bash handles are pending: their completion
+ // follow-ups are the wake-up, so keep the deferral without waking
+ // the parent with a subagent keep-alive and poll again after
+ // another window.
+ this._armAutonomousSubagentKeepAlive();
+ return;
+ }
if (!this._deliverAutonomousSubagentKeepAlive()) {
// Admission raced a pause; retry after another window.
this._armAutonomousSubagentKeepAlive();
@@ -4017,9 +4051,10 @@ export class AgentSession {
if (signal?.aborted || this._goalState.status !== "active" || !this._goalState.objective) {
return [];
}
- // Delegating and ending the turn is correct behavior; hold the continuation
- // until descendants settle instead of re-prompting a waiting parent.
- if (this._hasUnsettledRlmQuiescenceWork()) {
+ // Delegating and ending the turn is correct behavior; hold the
+ // continuation until descendants settle or the background bash
+ // handles finish instead of re-prompting a waiting parent.
+ if (this._hasUnsettledRlmQuiescenceWork() || this._hasLiveBackgroundBashHandles()) {
this._goalContinuationAwaitsRlmWork = true;
return [];
}
@@ -10371,6 +10406,10 @@ export class AgentSession {
snapshotDir: this._ipythonKernelSnapshotDir,
readyGate: previousDispose,
onRestore: notifyRestore ? (result) => this._onIpythonStateRestored(result) : undefined,
+ onBackgroundWorkSettled: () => {
+ this._maybeResumeGoalContinuationAfterRlmWork();
+ this._maybeResumeAutonomousContinuationAfterRlmWork();
+ },
});
configuredBaseToolDefinitions = createAllToolDefinitions(this._cwd, {
ipython: {
diff --git a/packages/coding-agent/src/core/kernel/repl-manager.ts b/packages/coding-agent/src/core/kernel/repl-manager.ts
index 396e284281..4e58527563 100644
--- a/packages/coding-agent/src/core/kernel/repl-manager.ts
+++ b/packages/coding-agent/src/core/kernel/repl-manager.ts
@@ -172,6 +172,7 @@ export class ReplKernelManager {
| "env"
| "sessionId"
| "hostHandlers"
+ | "onBackgroundWorkSettled"
| "pythonSkills"
| "snapshot"
| "bootstrapCode"
@@ -230,6 +231,7 @@ export class ReplKernelManager {
env: options.env,
sessionId: options.sessionId,
hostHandlers: options.hostHandlers,
+ onBackgroundWorkSettled: options.onBackgroundWorkSettled,
pythonSkills: options.pythonSkills,
snapshot: options.snapshot,
bootstrapCode: options.bootstrapCode,
@@ -805,6 +807,17 @@ export class ReplKernelManager {
}
} else if (this.backgroundBashHandles.get(activity.id) === activity.pid) {
this.backgroundBashHandles.delete(activity.id);
+ if (this.backgroundBashHandles.size === 0) {
+ // The last live handle settled: the completion notice for it
+ // is already admitted, so owed continuations may resume. A
+ // host callback failure must not break the event path.
+ try {
+ this.options.onBackgroundWorkSettled?.();
+ } catch (error) {
+ // The settlement already happened on the map.
+ this.appendKernelDiagnostic(`background work settled callback failed: ${errorMessage(error)}`);
+ }
+ }
}
}
return;
@@ -1328,7 +1341,18 @@ export class ReplKernelManager {
this.clearSnapshotTimer();
this.lateSentAgentMessageHandlers.clear();
this.pendingDoneWaiters.clear();
- this.backgroundBashHandles.clear();
+ // Teardown kills the handles with the kernel, so owed continuations
+ // waiting on them must hear the settlement once before it is lost. A
+ // host callback failure must not abort the kernel teardown.
+ if (this.backgroundBashHandles.size > 0) {
+ this.backgroundBashHandles.clear();
+ try {
+ this.options.onBackgroundWorkSettled?.();
+ } catch (error) {
+ // The settlement already happened on the map; teardown continues.
+ this.appendKernelDiagnostic(`background work settled callback failed: ${errorMessage(error)}`);
+ }
+ }
// Stale pre-teardown background output must not surface after a restart.
this.pendingBackgroundOutput = "";
this.pendingBackgroundOutputTruncated = false;
diff --git a/packages/coding-agent/src/core/kernel/shared.ts b/packages/coding-agent/src/core/kernel/shared.ts
index 71b7ef7377..d4bea5e423 100644
--- a/packages/coding-agent/src/core/kernel/shared.ts
+++ b/packages/coding-agent/src/core/kernel/shared.ts
@@ -51,6 +51,8 @@ export interface KernelManagerOptions {
env?: Record<string, string>;
sessionId?: string;
hostHandlers?: HostRequestHandlers;
+ /** Fires when the last live background bash() handle settles (its activity track empties or the kernel tears down). */
+ onBackgroundWorkSettled?: () => void;
pythonSkills?: readonly KernelPythonSkill[];
/** Persist/revive the user namespace across kernel restarts and session resume. */
snapshot?: KernelSnapshotConfig;
diff --git a/packages/coding-agent/src/core/tools/ipython.ts b/packages/coding-agent/src/core/tools/ipython.ts
index a9f696a2b8..808031a5f3 100644
--- a/packages/coding-agent/src/core/tools/ipython.ts
+++ b/packages/coding-agent/src/core/tools/ipython.ts
@@ -293,6 +293,8 @@ export interface IpythonToolOptions {
* (some names restored or some failed), so the session can tell the model.
*/
onRestore?: (result: RestoreResult) => void;
+ /** Fires when the kernel's last live background bash() handle settles, so owed continuations can resume. */
+ onBackgroundWorkSettled?: () => void;
onLateSentAgentMessage?: (toolCallId: string, message: KernelSentAgentMessage) => void;
/** Shared provisioner owning the kernel lifecycle. When provided, the remaining options are ignored. */
provisioner?: IpythonKernelProvisioner;
@@ -475,6 +477,7 @@ export class IpythonKernelProvisioner {
},
sessionId: this.options?.sessionId,
hostHandlers: this.options?.hostHandlers,
+ onBackgroundWorkSettled: this.options?.onBackgroundWorkSettled,
pythonSkills: this.options?.pythonSkills,
// Only persistent sessions (which have an artifact dir) get a revivable snapshot.
snapshot: snapshotDir
diff --git a/packages/coding-agent/test/autonomous-continuation-subagent-gate.test.ts b/packages/coding-agent/test/autonomous-continuation-subagent-gate.test.ts
index 806f49478f..95a5e16bf4 100644
--- a/packages/coding-agent/test/autonomous-continuation-subagent-gate.test.ts
+++ b/packages/coding-agent/test/autonomous-continuation-subagent-gate.test.ts
@@ -29,6 +29,7 @@ type FakeSession = {
_autonomousContinuationSuppressionDepth: number;
_autonomousContinuationSuppressedMessages: WeakSet<object>;
_hasUnsettledRlmQuiescenceWork: () => boolean;
+ _hasLiveBackgroundBashHandles: () => boolean;
_rlmTerminalNoticeAdmissionCount: number;
_admitSessionInput: ReturnType<typeof vi.fn>;
_createPreparedTurnAction: ReturnType<typeof vi.fn>;
@@ -84,6 +85,7 @@ function fakeSession(overrides: Partial<FakeSession> = {}): FakeSession {
_autonomousContinuationSuppressionDepth: 0,
_autonomousContinuationSuppressedMessages: new WeakSet(),
_hasUnsettledRlmQuiescenceWork: () => false,
+ _hasLiveBackgroundBashHandles: () => false,
_rlmTerminalNoticeAdmissionCount: 0,
_admitSessionInput: vi.fn(),
_createPreparedTurnAction: vi.fn(
@@ -150,6 +152,23 @@ describe("autonomous continuation vs active subagents", () => {
expect(vi.getTimerCount()).toBe(1);
});
+ it("holds the timer-driven continuation while a background bash handle runs without spending budget", async () => {
+ vi.useFakeTimers();
+ const session = fakeSession({ _hasLiveBackgroundBashHandles: () => true });
+ expect(await getContinuationMessages.call(session, context)).toEqual([]);
+ expect(session._autonomousContinuationAwaitsRlmWork).toBe(true);
+ expect(session._autonomousState.continuationsUsed).toBe(0);
+ });
+ it("re-polls the keep-alive instead of waking the parent while only background handles run", () => {
+ vi.useFakeTimers();
+ const session = fakeSession({ _hasLiveBackgroundBashHandles: () => true });
+ session._autonomousState.subagentKeepAliveMs = 1_000;
+ expect(holdForRlmWork.call(session, stoppedTurn)).toBe(true);
+ vi.advanceTimersByTime(1_000);
+ expect(session._admitSessionInput).not.toHaveBeenCalled();
+ expect(session._autonomousContinuationAwaitsRlmWork).toBe(true);
+ expect(vi.getTimerCount()).toBe(1);
+ });
it("holds without queueing behind an active goal continuation", () => {
vi.useFakeTimers();
const session = fakeSession({
diff --git a/packages/coding-agent/test/goal-continuation-quiescence.test.ts b/packages/coding-agent/test/goal-continuation-quiescence.test.ts
index 53e639f5db..f26649abc5 100644
--- a/packages/coding-agent/test/goal-continuation-quiescence.test.ts
+++ b/packages/coding-agent/test/goal-continuation-quiescence.test.ts
@@ -9,6 +9,7 @@ type Harness = {
_sessionInputAdmissionPauses: Set<symbol>;
_sessionInputPumpSuspended: boolean;
_hasUnsettledRlmQuiescenceWork: () => boolean;
+ _hasLiveBackgroundBashHandles: () => boolean;
_stopGoalContinuationForTerminalMessage: () => boolean;
_ensureGoalRuntimeActive: () => void;
_setGoalState: (goal: unknown) => void;
@@ -33,6 +34,7 @@ function harness(overrides: Partial<Harness> = {}): Harness {
_sessionInputAdmissionPauses: new Set(),
_sessionInputPumpSuspended: false,
_hasUnsettledRlmQuiescenceWork: () => false,
+ _hasLiveBackgroundBashHandles: () => false,
_stopGoalContinuationForTerminalMessage: () => false,
_ensureGoalRuntimeActive: () => {},
_setGoalState: function (this: Harness, goal: unknown) {
@@ -65,6 +67,15 @@ describe("goal continuation vs unsettled subagent work", () => {
expect(mode._goalState.continuationsUsed).toBe(1);
});
+ it("defers the continuation while a background bash handle runs and keeps the deferral on resume", async () => {
+ const mode = harness({ _hasLiveBackgroundBashHandles: () => true });
+ await expect(getGoalContinuation.call(mode, context)).resolves.toEqual([]);
+ expect(mode._goalContinuationAwaitsRlmWork).toBe(true);
+ expect(mode._goalState.continuationsUsed).toBe(0);
+ maybeResume.call(mode);
+ expect(mode._admitSessionInput).not.toHaveBeenCalled();
+ expect(mode._goalContinuationAwaitsRlmWork).toBe(true);
+ });
it("resumes a deferred continuation exactly once, unqueued, idle-waking, and counted", () => {
const mode = harness({ _goalContinuationAwaitsRlmWork: true });
maybeResume.call(mode);
diff --git a/packages/coding-agent/test/suite/regressions/2053-background-bash-passivation.test.ts b/packages/coding-agent/test/suite/regressions/2053-background-bash-passivation.test.ts
index 4da5a7745d..7c16558537 100644
--- a/packages/coding-agent/test/suite/regressions/2053-background-bash-passivation.test.ts
+++ b/packages/coding-agent/test/suite/regressions/2053-background-bash-passivation.test.ts
@@ -58,6 +58,7 @@ describeRuntime("#2053 background kernel bash residency", () => {
async function start(
beforeCompletion?: () => Promise<void>,
withConfiguredAuth = true,
+ settled?: () => void,
): Promise<{ session: AgentSession; kernel: ReplKernelManager }> {
harness = await createHarness({ tools: [], rlmDepth: 1, withConfiguredAuth });
const session = harness.session;
@@ -73,6 +74,7 @@ describeRuntime("#2053 background kernel bash residency", () => {
cwd: harness.tempDir,
env: { PYTHONPATH: resolve(runtimeDir, "src") },
hostHandlers,
+ ...(settled ? { onBackgroundWorkSettled: settled } : {}),
});
const provisioner = new IpythonKernelProvisioner(harness.tempDir);
vi.spyOn(provisioner, "manager", "get").mockReturnValue(manager);
@@ -123,7 +125,8 @@ describeRuntime("#2053 background kernel bash residency", () => {
});
it("keeps concurrent handles resident until the final completion and clears on kernel teardown", async () => {
- const { session, kernel } = await start();
+ const settled = vi.fn();
+ const { session, kernel } = await start(undefined, true, settled);
await kernel.execute("from rlm import bash\nfirst = bash('sleep 600')\nsecond = bash('sleep 600')");
expect(passivationAllowed(session)).toBe(false);
harness!.setResponses([fauxAssistantMessage("First command finished.")]);
@@ -133,6 +136,7 @@ describeRuntime("#2053 background kernel bash residency", () => {
expect(passivationAllowed(session)).toBe(false);
await kernel.kill();
+ expect(settled).toHaveBeenCalledTimes(1);
expect(passivationAllowed(session)).toBe(true);
expect(
session.messages.filter(
@@ -271,7 +275,8 @@ describeRuntime("#2053 background kernel bash residency", () => {
describe("kernel bash activity validation", () => {
it("ignores unrelated display data and rejects malformed or mismatched releases", async () => {
- const kernel = new ReplKernelManager({});
+ const settled = vi.fn();
+ const kernel = new ReplKernelManager({ onBackgroundWorkSettled: settled });
const deliver = (data: Record<string, unknown>) =>
(kernel as unknown as { handleEvent(event: Record<string, unknown>): void }).handleEvent({
event: "display",
@@ -281,6 +286,7 @@ describe("kernel bash activity validation", () => {
const activity = { id: "a".repeat(32), pid: 42, active: true };
deliver({ [BASH_ACTIVITY_DISPLAY_MIME]: activity });
expect(kernel.hasBackgroundWork).toBe(true);
+ expect(settled).not.toHaveBeenCalled();
for (const invalid of [
{ ...activity, pid: 0, active: false },
{ ...activity, pid: -1, active: false },
@@ -297,6 +303,8 @@ describe("kernel bash activity validation", () => {
expect(kernel.hasBackgroundWork).toBe(true);
deliver({ [BASH_ACTIVITY_DISPLAY_MIME]: { ...activity, active: false } });
expect(kernel.hasBackgroundWork).toBe(false);
+ expect(settled).toHaveBeenCalledTimes(1);
await kernel.shutdown();
+ expect(settled).toHaveBeenCalledTimes(1);
});
});