@code-yeongyu/senpi 2026.11.6-3 → 2026.11.9-2

package/dist/core/extensions/builtin/terminal/background-age.js

@@ -0,0 +1,91 @@
+const MINUTE_MS = 60_000;
+const BACKGROUND_AGE_FIRST_MS = 10 * MINUTE_MS;
+const BACKGROUND_AGE_REPEAT_MS = 30 * MINUTE_MS;
+const MAX_TIMER_MS = 2_147_483_647;
+/** The first age milestone strictly after `ageMs`. */
+function nextAgeMilestoneMs(ageMs) {
+    if (ageMs < BACKGROUND_AGE_FIRST_MS)
+        return BACKGROUND_AGE_FIRST_MS;
+    const repeats = Math.floor((ageMs - BACKGROUND_AGE_FIRST_MS) / BACKGROUND_AGE_REPEAT_MS) + 1;
+    return BACKGROUND_AGE_FIRST_MS + repeats * BACKGROUND_AGE_REPEAT_MS;
+}
+export function backgroundAgeEvent(kind, subject, nowMs) {
+    const ageMs = Math.max(0, nowMs - subject.startedAtMs);
+    return {
+        kind,
+        id: subject.id,
+        description: subject.description,
+        ...(subject.command === undefined ? {} : { command: subject.command }),
+        startedAtMs: subject.startedAtMs,
+        ageMs,
+        ageMinutes: Math.floor(ageMs / MINUTE_MS),
+        autoReapMinutes: subject.autoReapMinutes ?? null,
+        stop: { tool: "kill_bash", args: { bash_id: subject.id } },
+    };
+}
+export class BackgroundAgeSchedule {
+    #entries = new Map();
+    #onDue;
+    #timer;
+    constructor(onDue) {
+        this.#onDue = onDue;
+    }
+    add(subject) {
+        const now = Date.now();
+        this.#entries.set(subject.id, {
+            subject,
+            dueAtMs: subject.startedAtMs + nextAgeMilestoneMs(now - subject.startedAtMs),
+        });
+        this.#arm(now);
+    }
+    get(id) {
+        return this.#entries.get(id)?.subject;
+    }
+    remove(id) {
+        const entry = this.#entries.get(id);
+        if (!entry)
+            return undefined;
+        this.#entries.delete(id);
+        this.#arm(Date.now());
+        return entry.subject;
+    }
+    dispose() {
+        this.#entries.clear();
+        this.#clearTimer();
+    }
+    #fire() {
+        this.#timer = undefined;
+        const now = Date.now();
+        const due = [];
+        for (const entry of this.#entries.values()) {
+            if (entry.dueAtMs > now)
+                continue;
+            const ageMs = now - entry.subject.startedAtMs;
+            due.push(backgroundAgeEvent("running", entry.subject, now));
+            entry.dueAtMs = entry.subject.startedAtMs + nextAgeMilestoneMs(ageMs);
+        }
+        this.#arm(now);
+        for (const event of due)
+            this.#onDue(event);
+    }
+    #arm(now) {
+        this.#clearTimer();
+        let earliest;
+        for (const entry of this.#entries.values()) {
+            if (earliest === undefined || entry.dueAtMs < earliest)
+                earliest = entry.dueAtMs;
+        }
+        if (earliest === undefined)
+            return;
+        const timer = setTimeout(() => this.#fire(), Math.min(Math.max(0, earliest - now), MAX_TIMER_MS));
+        timer.unref?.();
+        this.#timer = timer;
+    }
+    #clearTimer() {
+        if (this.#timer === undefined)
+            return;
+        clearTimeout(this.#timer);
+        this.#timer = undefined;
+    }
+}
+//# sourceMappingURL=background-age.js.map

package/dist/core/extensions/builtin/terminal/extension-state.d.ts

@@ -2,7 +2,7 @@
 import type { ExtensionAPI, ExtensionContext } from "../../types.ts";
 import type { MonitorNotifier } from "./monitor-notify.ts";
 import type { MonitorStatusTicker } from "./monitor-status-ticker.ts";
-import type { TerminalNotifier } from "./notify.ts";
+import { type TerminalNotifier } from "./notify.ts";
 import type { PersistenceState } from "./restore-session.ts";
 import { type TerminalEventSinks, TerminalSessionBundle } from "./session-bundle.ts";
 import type { ResolvedTerminalSettings } from "./settings.ts";

package/dist/core/extensions/builtin/terminal/extension-state.js

@@ -1,9 +1,10 @@
 /** The terminal extension's per-generation state, the bundle event sinks it binds, and the tool context over it. */
 import { getShellEnv } from "../../../../utils/shell.js";
-import { TERMINAL_MONITOR_ENDED_EVENT, TERMINAL_MONITOR_STATE_EVENT, WAKE_SOURCE_STATE_EVENT, } from "../monitor-state-event.js";
+import { TERMINAL_BACKGROUND_AGE_EVENT, TERMINAL_MONITOR_ENDED_EVENT, TERMINAL_MONITOR_STATE_EVENT, WAKE_SOURCE_STATE_EVENT, } from "../monitor-state-event.js";
 import { withTerminalContext } from "./context-lifetime.js";
 import { tapBackgroundSession, untapBackgroundSession } from "./job-widget-tap.js";
 import { removeMonitorStateDir, terminalStateDir } from "./monitor-state-dir.js";
+import { describeBackgroundAge } from "./notify.js";
 import { TerminalSessionBundle } from "./session-bundle.js";
 /** Tests and SDK callers may hand partial contexts without a session manager. */
 export function sessionKeyOf(ctx) {
@@ -101,6 +102,14 @@ export function bundleSinks(pi, state) {
             }
             record();
         },
+        onBackgroundAge: (event) => {
+            pi.events?.emit(TERMINAL_BACKGROUND_AGE_EVENT, event);
+            pi.rpc?.emit(TERMINAL_BACKGROUND_AGE_EVENT, event);
+            withTerminalContext(() => state.ctx?.ui?.notify?.(describeBackgroundAge(event), event.kind === "running" ? "info" : "warning"), retire);
+            // A reap reaches the model through the session's completion notice, which names the reap.
+            if (event.kind !== "reaped")
+                state.notifier?.notifyAge(event);
+        },
         onBackgroundExit: (id, runtime) => {
             state.recordedBackgroundIds.delete(id);
             if (state.manifestWriter)
@@ -146,6 +155,9 @@ export function buildToolContext(pi, state) {
         get maxDurableMonitors() {
             return state.settings.maxDurableMonitors;
         },
+        get backgroundAutoReapMinutes() {
+            return state.settings.backgroundAutoReapMinutes;
+        },
         get monitorRegistry() {
             return requireBundle().monitors;
         },
@@ -153,8 +165,11 @@ export function buildToolContext(pi, state) {
         getSessionContext: () => state.ctx,
         // Exit listeners registered before a reload reach the post-reload owner through the
         // shared bundle, so this must dispatch via the bundle, never the instance notifier.
-        onBackgroundStart: (id, description, startedAtMs, command) => {
-            state.bundle?.notifyBackgroundStart(id, description, startedAtMs);
+        onBackgroundStart: (id, description, startedAtMs, command, autoReapMinutes) => {
+            state.bundle?.notifyBackgroundStart(id, description, startedAtMs, {
+                ...(command === undefined ? {} : { command }),
+                ...(autoReapMinutes === undefined ? {} : { autoReapMinutes }),
+            });
             const runtime = state.bundle?.manager.get(id);
             if (runtime) {
                 const key = withTerminalContext(() => sessionKeyOf(state.ctx), () => { });
@@ -168,6 +183,9 @@ export function buildToolContext(pi, state) {
         onBackgroundExit: (id, runtime) => {
             state.bundle?.notifyBackgroundExit(id, runtime);
         },
+        onBackgroundReapFailed: (id, autoReapMinutes, reason) => {
+            state.bundle?.notifyBackgroundReapFailed(id, autoReapMinutes, reason);
+        },
         onMonitorRearmed: (id) => state.monitorNotifier?.rearm(id),
         onMonitorsResumed: (ids) => state.monitorNotifier?.resume(ids),
         ensurePersistence: () => state.ensurePersistence?.() ?? Promise.resolve(),

package/dist/core/extensions/builtin/terminal/notify.d.ts

@@ -1,4 +1,5 @@
 import type { ExtensionContext } from "../../types.ts";
+import type { TerminalBackgroundAgeEvent } from "../monitor-state-event.ts";
 import type { NotifyMode } from "./settings.ts";
 import type { TerminalExitView } from "./tools/context.ts";
 /** Modes that never wake the agent: one-shot, non-interactive runs. */
@@ -28,6 +29,8 @@ export interface TerminalNotificationDelivery {
 }
 /** Shared terminal-notification guard and notify-mode mapping. */
 export declare function getTerminalNotificationDelivery(deps: TerminalNotifierDeps, customType?: string): TerminalNotificationDelivery | undefined;
+/** One plain sentence (or two) for the TUI and the model: which session, how old, and how it stops. */
+export declare function describeBackgroundAge(event: TerminalBackgroundAgeEvent): string;
 /**
  * Notifies an interactive agent once when a background session completes.
  *
@@ -41,6 +44,9 @@ export declare class TerminalNotifier {
     private retired;
     constructor(deps: TerminalNotifierDeps);
     notifyCompletion(id: string, runtime: TerminalExitView): void;
+    /** A still-running session's age notice (senpi#6201), delivered like a completion notice. */
+    notifyAge(event: TerminalBackgroundAgeEvent): void;
+    private retire;
     private deliverCompletion;
 }
 //# sourceMappingURL=notify.d.ts.map

package/dist/core/extensions/builtin/terminal/notify.js

@@ -27,7 +27,34 @@ export function getTerminalNotificationDelivery(deps, customType = TERMINAL_NOTI
         }),
     };
 }
+function minutes(count) {
+    return `${count} minute${count === 1 ? "" : "s"}`;
+}
+function killCall(id) {
+    return `kill_bash({ bash_id: "${id}" })`;
+}
+/** One plain sentence (or two) for the TUI and the model: which session, how old, and how it stops. */
+export function describeBackgroundAge(event) {
+    const label = event.command === undefined || event.command === event.description
+        ? event.description
+        : `${event.description}: ${event.command}`;
+    const session = `Background terminal session ${event.id} (${label})`;
+    if (event.kind === "reaped") {
+        return `${session} was stopped automatically after ${minutes(event.autoReapMinutes ?? event.ageMinutes)} (auto-reap).`;
+    }
+    if (event.kind === "reap_failed") {
+        return `${session} is still running: auto-reap at ${minutes(event.autoReapMinutes ?? event.ageMinutes)} failed (${event.reason ?? "unknown reason"}) and will not retry; stop it with ${killCall(event.id)} if it is no longer needed.`;
+    }
+    const reap = event.autoReapMinutes === null
+        ? "Nothing stops it automatically"
+        : `Auto-reap stops it at ${minutes(event.autoReapMinutes)}`;
+    return `${session} has been running for ${minutes(event.ageMinutes)}. ${reap}; stop it now with ${killCall(event.id)} if it is no longer needed.`;
+}
 function buildNotice(id, runtime, trustText) {
+    const reaped = runtime.autoReapedAfterMinutes;
+    const reapText = reaped === undefined
+        ? ""
+        : ` It was stopped automatically after ${minutes(reaped)} (auto-reap: the auto_reap_minutes parameter or the terminal.backgroundAutoReapMinutes setting).`;
     const status = describeExit(runtime) ?? "exited";
     const code = runtime.exitResult?.exitCode;
     const codeText = code === null || code === undefined ? "" : ` (exit code ${code})`;
@@ -42,7 +69,7 @@ function buildNotice(id, runtime, trustText) {
         tailSection = `\nFinal output:\n${shown}${note}`;
     }
     const trustSection = trustText === undefined ? "" : `\n${trustText}`;
-    return `<system-reminder>Background terminal session ${id} finished: ${status}${codeText}.${tailSection}${trustSection}</system-reminder>`;
+    return `<system-reminder>Background terminal session ${id} finished: ${status}${codeText}.${reapText}${tailSection}${trustSection}</system-reminder>`;
 }
 /**
  * Notifies an interactive agent once when a background session completes.
@@ -60,10 +87,17 @@ export class TerminalNotifier {
     notifyCompletion(id, runtime) {
         if (this.retired || this.notified.has(id))
             return;
-        withTerminalContext(() => this.deliverCompletion(id, runtime), () => {
-            this.retired = true;
-            this.notified.clear();
-        });
+        withTerminalContext(() => this.deliverCompletion(id, runtime), () => this.retire());
+    }
+    /** A still-running session's age notice (senpi#6201), delivered like a completion notice. */
+    notifyAge(event) {
+        if (this.retired || this.notified.has(event.id))
+            return;
+        withTerminalContext(() => getTerminalNotificationDelivery(this.deps)?.send(`<system-reminder>${describeBackgroundAge(event)}</system-reminder>`, { details: { backgroundAge: event } }), () => this.retire());
+    }
+    retire() {
+        this.retired = true;
+        this.notified.clear();
     }
     deliverCompletion(id, runtime) {
         const delivery = getTerminalNotificationDelivery(this.deps);

package/dist/core/extensions/builtin/terminal/session-bundle.d.ts

@@ -1,4 +1,4 @@
-import type { WakeSourceStateItem } from "../monitor-state-event.ts";
+import type { TerminalBackgroundAgeEvent, WakeSourceStateItem } from "../monitor-state-event.ts";
 import { TerminalManager, type TerminalManagerOptions } from "./manager.ts";
 import type { MonitorEndedEvent } from "./monitor-registry.ts";
 import { type MonitorEvent, MonitorRegistry, type MonitorSnapshotEntry } from "./monitor-registry.ts";
@@ -9,6 +9,11 @@ export interface TerminalEventSinks {
     readonly onMonitorEnded: (event: MonitorEndedEvent) => void;
     readonly onBackgroundState: (snapshot: readonly WakeSourceStateItem[]) => void;
     readonly onBackgroundExit: (id: string, runtime: TerminalExitView) => void;
+    readonly onBackgroundAge: (event: TerminalBackgroundAgeEvent) => void;
+}
+export interface BackgroundStartDetails {
+    readonly command?: string;
+    readonly autoReapMinutes?: number;
 }
 /**
  * The long-lived terminal runtime for one agent session: the PTY session manager plus
@@ -26,7 +31,9 @@ export declare class TerminalSessionBundle {
     bind(sinks: TerminalEventSinks): void;
     park(): void;
     backgroundSnapshot(): readonly WakeSourceStateItem[];
-    notifyBackgroundStart(id: string, description: string, startedAtMs?: number): void;
+    notifyBackgroundStart(id: string, description: string, startedAtMs?: number, details?: BackgroundStartDetails): void;
+    /** The auto-reap's stop did not end a session still on the schedule: one notice; its age notices go on. */
+    notifyBackgroundReapFailed(id: string, autoReapMinutes: number, reason: string): void;
     notifyBackgroundExit(id: string, runtime: TerminalExitView): void;
     teardown(): Promise<void>;
 }

package/dist/core/extensions/builtin/terminal/session-bundle.js

@@ -1,3 +1,4 @@
+import { BackgroundAgeSchedule, backgroundAgeEvent } from "./background-age.js";
 import { TerminalManager } from "./manager.js";
 import { MonitorRegistry } from "./monitor-registry.js";
 const MAX_PARKED_MONITOR_EVENTS = 100;
@@ -15,6 +16,9 @@ export class TerminalSessionBundle {
     #parkedMonitorEndings = [];
     #parkedExits = new Map();
     #backgrounds = new Map();
+    #ages = new BackgroundAgeSchedule((event) => this.#dispatchAge(event));
+    /** Age events that came due while parked: only the newest per session is worth delivering. */
+    #parkedAges = new Map();
     #torndown = false;
     constructor(options) {
         this.manager = new TerminalManager(options);
@@ -41,6 +45,8 @@ export class TerminalSessionBundle {
         this.#parkedMonitorEndings = [];
         const parkedExits = [...this.#parkedExits];
         this.#parkedExits.clear();
+        const parkedAges = [...this.#parkedAges.values()];
+        this.#parkedAges.clear();
         sinks.onMonitorState(this.monitors.snapshot());
         sinks.onBackgroundState(this.backgroundSnapshot());
         for (const event of parkedMonitorEvents)
@@ -49,6 +55,8 @@ export class TerminalSessionBundle {
             sinks.onMonitorEnded(event);
         for (const [id, runtime] of parkedExits)
             sinks.onBackgroundExit(id, runtime);
+        for (const event of parkedAges)
+            sinks.onBackgroundAge(event);
     }
     park() {
         this.#sinks = null;
@@ -56,15 +64,32 @@ export class TerminalSessionBundle {
     backgroundSnapshot() {
         return [...this.#backgrounds.values()];
     }
-    notifyBackgroundStart(id, description, startedAtMs = Date.now()) {
+    notifyBackgroundStart(id, description, startedAtMs = Date.now(), details = {}) {
         if (this.#torndown)
             return;
         this.#backgrounds.set(id, { id, description, startedAtMs });
+        this.#ages.add({ id, description, startedAtMs, ...details });
         this.#sinks?.onBackgroundState(this.backgroundSnapshot());
     }
+    /** The auto-reap's stop did not end a session still on the schedule: one notice; its age notices go on. */
+    notifyBackgroundReapFailed(id, autoReapMinutes, reason) {
+        if (this.#torndown)
+            return;
+        const subject = this.#ages.get(id);
+        if (!subject)
+            return;
+        const event = backgroundAgeEvent("reap_failed", { ...subject, autoReapMinutes }, Date.now());
+        this.#dispatchAge({ ...event, reason });
+    }
     notifyBackgroundExit(id, runtime) {
         if (this.#torndown)
             return;
+        const subject = this.#ages.remove(id);
+        this.#parkedAges.delete(id);
+        if (subject && runtime.autoReapedAfterMinutes !== undefined) {
+            const reaped = { ...subject, autoReapMinutes: runtime.autoReapedAfterMinutes };
+            this.#dispatchAge(backgroundAgeEvent("reaped", reaped, Date.now()));
+        }
         if (this.#backgrounds.delete(id))
             this.#sinks?.onBackgroundState(this.backgroundSnapshot());
         if (this.#sinks) {
@@ -80,6 +105,8 @@ export class TerminalSessionBundle {
             return;
         this.#parkedMonitorEvents = [];
         this.#parkedExits.clear();
+        this.#ages.dispose();
+        this.#parkedAges.clear();
         this.monitors.dispose();
         if (this.#backgrounds.size > 0) {
             this.#backgrounds.clear();
@@ -90,6 +117,14 @@ export class TerminalSessionBundle {
         this.#sinks = null;
         await this.manager.teardown();
     }
+    #dispatchAge(event) {
+        if (this.#torndown)
+            return;
+        if (this.#sinks)
+            this.#sinks.onBackgroundAge(event);
+        else
+            this.#parkedAges.set(event.id, event);
+    }
     #dispatchMonitorEvent(event) {
         if (this.#torndown)
             return;

package/dist/core/extensions/builtin/terminal/settings.d.ts

@@ -27,6 +27,8 @@ export interface ResolvedTerminalSettings {
     readonly monitorRunaway: MonitorRunawayGuard;
     /** Admission cap on persistent (restart-surviving) monitors per session. */
     readonly maxDurableMonitors: number | "unlimited";
+    /** Age in minutes at which a background session is stopped (senpi#6201); undefined means never (the default). */
+    readonly backgroundAutoReapMinutes: number | undefined;
 }
 export declare const TERMINAL_SETTINGS_DEFAULTS: ResolvedTerminalSettings;
 /** Upper bound of a wake rate (setting or per-monitor override): one wake a second on average. */

package/dist/core/extensions/builtin/terminal/settings.js

@@ -20,6 +20,7 @@ export const TERMINAL_SETTINGS_DEFAULTS = {
         minutes: DEFAULT_MONITOR_RUNAWAY_MINUTES,
     },
     maxDurableMonitors: "unlimited",
+    backgroundAutoReapMinutes: undefined,
 };
 /** Upper bound of a wake rate (setting or per-monitor override): one wake a second on average. */
 export const MAX_MONITOR_WAKES_PER_HOUR = 3600;
@@ -42,6 +43,12 @@ function durableMonitorCap(value) {
         return "unlimited";
     return Math.trunc(value);
 }
+/** A whole number of minutes >= 1 turns auto-reap on; anything else (unset, 0, negative, non-numeric) leaves it off. */
+function autoReapMinutes(value) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 1)
+        return undefined;
+    return Math.trunc(value);
+}
 /** Resolve terminal-tool config from a raw `terminal` settings block, filling defaults. */
 export function resolveTerminalSettings(raw) {
     if (!raw)
@@ -66,6 +73,7 @@ export function resolveTerminalSettings(raw) {
             minutes: positiveInt(raw.monitorRunawayMinutes, TERMINAL_SETTINGS_DEFAULTS.monitorRunaway.minutes, 1440),
         },
         maxDurableMonitors: durableMonitorCap(raw.maxDurableMonitors),
+        backgroundAutoReapMinutes: autoReapMinutes(raw.backgroundAutoReapMinutes),
     };
 }
 /** Load and merge terminal-tool settings from global + project settings.json. */

package/dist/core/extensions/builtin/terminal/tools/background-auto-reap.d.ts

@@ -0,0 +1,15 @@
+import type { TerminalRuntimeSession } from "../runtime-session.ts";
+import type { TerminalToolContext } from "./context.ts";
+export interface BackgroundSessionStart {
+    readonly description: string;
+    readonly command: string;
+    readonly startedAtMs: number;
+    readonly autoReapMinutes: number | undefined;
+}
+export declare function backgroundStart(input: {
+    readonly command: string;
+    readonly description?: string;
+    readonly auto_reap_minutes?: number;
+}, configuredMinutes: number | undefined, startedAtMs: number): BackgroundSessionStart;
+export declare function trackBackgroundSession(ctx: TerminalToolContext, id: string, runtime: TerminalRuntimeSession, start: BackgroundSessionStart): void;
+//# sourceMappingURL=background-auto-reap.d.ts.map

package/dist/core/extensions/builtin/terminal/tools/background-auto-reap.js

@@ -0,0 +1,87 @@
+/**
+ * A session that runs on in the background (`run_in_background`, or a foreground command that auto-detached) is
+ * announced to the host and, only when opted into (senpi#6201), stopped at a configured age. The reap runs here, where
+ * the session's process group lives (this process, or the tool child), through `manager.stop`: the same TERM-then-KILL
+ * stop `kill_bash` uses. Its one timer is unref'd and cleared when the session exits; with no opt-in none is armed.
+ * A reap counts only when that stop resolved and the session really exited; a stop that rejects or leaves the session
+ * running is reported once (`onBackgroundReapFailed`) and never retried, and the session keeps running.
+ */
+import { getAgentDir } from "../../../../../config.js";
+import { createSessionLogger } from "../../../../session-log.js";
+const MINUTE_MS = 60_000;
+const MAX_TIMER_MS = 2_147_483_647;
+/** The call's `auto_reap_minutes` wins over the setting; a whole number of minutes >= 1 reaps, 0 or less turns it off. */
+function resolveAutoReapMinutes(requested, configured) {
+    const value = requested ?? configured;
+    if (value === undefined || !Number.isFinite(value))
+        return undefined;
+    const minutes = Math.trunc(value);
+    return minutes >= 1 ? minutes : undefined;
+}
+export function backgroundStart(input, configuredMinutes, startedAtMs) {
+    return {
+        description: input.description ?? input.command,
+        command: input.command,
+        startedAtMs,
+        autoReapMinutes: resolveAutoReapMinutes(input.auto_reap_minutes, configuredMinutes),
+    };
+}
+function reapedView(runtime, minutes) {
+    return {
+        exitResult: runtime.exitResult,
+        autoReapedAfterMinutes: minutes,
+        fullOutput: () => runtime.fullOutput(),
+    };
+}
+export function trackBackgroundSession(ctx, id, runtime, start) {
+    ctx.onBackgroundStart?.(id, start.description, start.startedAtMs, start.command, start.autoReapMinutes);
+    const minutes = start.autoReapMinutes;
+    let reapedAfterMinutes;
+    /** The one reap attempt; the session's exit report waits for it, since the stop's own exit fires before it resolves. */
+    let reaping;
+    let timer;
+    const reap = async (age) => {
+        const failure = await ctx.manager.stop(id).then((stopped) => {
+            if (!stopped)
+                return `the terminal manager has no session ${id} to stop`;
+            return runtime.exited ? undefined : "the session was still running after the stop (TERM, then KILL)";
+        }, (error) => (error instanceof Error ? error.message : String(error)));
+        if (failure === undefined) {
+            reapedAfterMinutes = age;
+            return;
+        }
+        const logger = ctx.sessionLogger ?? createSessionLogger(getAgentDir());
+        logger.warn("bash_auto_reap_failed", { bash_id: id, autoReapMinutes: age, error: failure });
+        if (!runtime.exited)
+            ctx.onBackgroundReapFailed?.(id, age, failure);
+    };
+    const arm = (deadlineMs) => {
+        timer = setTimeout(() => {
+            timer = undefined;
+            if (runtime.exited || minutes === undefined)
+                return;
+            if (Date.now() < deadlineMs) {
+                arm(deadlineMs);
+                return;
+            }
+            // Recorded before the stop starts: the exit it causes can fire from inside `stop` itself.
+            reaping = Promise.resolve().then(() => reap(minutes));
+        }, Math.min(Math.max(0, deadlineMs - Date.now()), MAX_TIMER_MS));
+        timer.unref?.();
+    };
+    if (minutes !== undefined && !runtime.exited)
+        arm(start.startedAtMs + minutes * MINUTE_MS);
+    if (minutes === undefined && !ctx.onBackgroundExit)
+        return;
+    runtime.session.onExit(() => {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        timer = undefined;
+        const report = () => ctx.onBackgroundExit?.(id, reapedAfterMinutes === undefined ? runtime : reapedView(runtime, reapedAfterMinutes));
+        if (reaping === undefined)
+            report();
+        else
+            void reaping.then(report);
+    });
+}
+//# sourceMappingURL=background-auto-reap.js.map

package/dist/core/extensions/builtin/terminal/tools/bash.d.ts

@@ -6,6 +6,7 @@ export declare const ptyBashSchema: Type.TObject<{
     timeout: Type.TOptional<Type.TNumber>;
     description: Type.TOptional<Type.TString>;
     run_in_background: Type.TOptional<Type.TBoolean>;
+    auto_reap_minutes: Type.TOptional<Type.TNumber>;
     cols: Type.TOptional<Type.TNumber>;
     rows: Type.TOptional<Type.TNumber>;
 }>;
@@ -50,6 +51,7 @@ export declare function createPtyBashTool(ctx: TerminalToolContext): {
         timeout: Type.TOptional<Type.TNumber>;
         description: Type.TOptional<Type.TString>;
         run_in_background: Type.TOptional<Type.TBoolean>;
+        auto_reap_minutes: Type.TOptional<Type.TNumber>;
         cols: Type.TOptional<Type.TNumber>;
         rows: Type.TOptional<Type.TNumber>;
     }>;

package/dist/core/extensions/builtin/terminal/tools/bash.js

@@ -6,6 +6,7 @@ import { stallThresholdMs, watchForStall } from "../../../../stall-warning.js";
 import { formatTerminalToolOutput } from "../output-format.js";
 import { BACKGROUND_START_GRACE_MS, DEFAULT_COLS, DEFAULT_ROWS, FOREGROUND_ENV_OVERRIDES, KILLED_SESSION_EXIT_GRACE_MS, TERMINAL_BASH_TOOL, } from "../shared.js";
 import { errorResult, noticedResult, textResult, } from "./context.js";
+import { backgroundStart, trackBackgroundSession } from "./background-auto-reap.js";
 import { createForegroundDetachGate } from "./foreground-detach.js";
 import { resolveForegroundWindowSeconds, SLEEP_WAIT_WINDOW_SECONDS } from "./foreground-window.js";
 import { classifySleepWait } from "./sleep-wait.js";
@@ -19,6 +20,9 @@ export const ptyBashSchema = Type.Object({
     run_in_background: Type.Optional(Type.Boolean({
         description: "Run as a persistent background session: returns a bash_id immediately (read with bash_output, steer with bash_input, stop with kill_bash). A plain & job dies with the call's PTY hangup (native backend), and nohup at best leaves an untracked orphan (no bash_id, no log) that the call's timeout still group-kills. This flag is the only reliable way a job outlives the call.",
     })),
+    auto_reap_minutes: Type.Optional(Type.Number({
+        description: "Background sessions only: stop this session (TERM, then KILL to its process group) once it has run this many minutes. Defaults to the terminal.backgroundAutoReapMinutes setting, which is off; 0 turns it off for this call.",
+    })),
     cols: Type.Optional(Type.Number({ description: "PTY width in columns (default 120)." })),
     rows: Type.Optional(Type.Number({ description: "PTY height in rows (default 40)." })),
 });
@@ -306,9 +310,7 @@ async function runForeground(ctx, input, cols, rows, signal, cwd, onUpdate, tool
     }
     if (outcome === "detached") {
         scheduleDetachedSweep(ctx, id, runtime, timeoutMs, startedAt);
-        ctx.onBackgroundStart?.(id, input.description ?? input.command, startedAt, input.command);
-        if (ctx.onBackgroundExit)
-            runtime.session.onExit(() => ctx.onBackgroundExit?.(id, runtime));
+        trackBackgroundSession(ctx, id, runtime, backgroundStart(input, ctx.backgroundAutoReapMinutes, startedAt));
         const delta = runtime.readDelta();
         const partialOutput = formatTerminalToolOutput(delta.text).text || "(no output yet)";
         const timeoutNote = input.timeout !== undefined && Number.isFinite(input.timeout)
@@ -373,9 +375,7 @@ async function runBackground(ctx, input, cols, rows, cwd, toolCallId, execCtx) {
         cwd,
         envOverrides: sessionEnvOverrides(ctx, execCtx),
     }, toolCallId, execCtx);
-    ctx.onBackgroundStart?.(id, input.description ?? input.command, Date.now(), input.command);
-    if (ctx.onBackgroundExit)
-        runtime.session.onExit(() => ctx.onBackgroundExit?.(id, runtime));
+    trackBackgroundSession(ctx, id, runtime, backgroundStart(input, ctx.backgroundAutoReapMinutes, Date.now()));
     // Capture any output the command emits within a short grace window (or its exit).
     await Promise.race([delay(BACKGROUND_START_GRACE_MS), runtime.session.waitExit()]);
     const early = formatTerminalToolOutput(runtime.readDelta().text).text;

package/dist/core/extensions/builtin/terminal/tools/child-placement.d.ts

@@ -27,11 +27,19 @@ export type TerminalBackgroundWake = {
     readonly id: string;
     readonly description: string;
     readonly startedAtMs: number;
+    readonly command?: string;
+    readonly autoReapMinutes?: number;
 } | {
     readonly event: "background_exit";
     readonly id: string;
     readonly exit: TerminalExitView["exitResult"];
     readonly output: string;
+    readonly autoReapedAfterMinutes?: number;
+} | {
+    readonly event: "background_reap_failed";
+    readonly id: string;
+    readonly autoReapMinutes: number;
+    readonly reason: string;
 };
 export declare function lostSessionResult(id: string, generation: number): AgentToolResult<unknown>;
 export declare function terminalChildJob(ctx: TerminalToolContext, kind: (typeof TERMINAL_CHILD_JOB_KINDS)[keyof typeof TERMINAL_CHILD_JOB_KINDS]): ToolChildJob;