opencode-matrixx 2.6.6 → 2.6.7

package/dist/cli.js

@@ -15787,6 +15787,20 @@ var CircuitBreakerConfigSchema = exports_external.object({
   maxToolCalls: exports_external.number().int().min(10).optional(),
   consecutiveThreshold: exports_external.number().int().min(5).optional()
 });
+var NestedAdmissionConfigSchema = exports_external.object({
+  enabled: exports_external.boolean().optional(),
+  mode: exports_external.enum(["bypass", "reserve"]).optional(),
+  maxDepth: exports_external.number().int().min(1).max(5).optional()
+});
+var WakeSchedulerConfigSchema = exports_external.object({
+  enabled: exports_external.boolean().optional(),
+  intervalMs: exports_external.number().min(60000).optional()
+});
+var JobBoardConfigSchema = exports_external.object({
+  enabled: exports_external.boolean().optional(),
+  strategy: exports_external.enum(["latest", "checkpoint-compatible"]).optional(),
+  maxRetainedSnapshots: exports_external.number().int().min(1).max(100).optional()
+});
 var BackgroundTaskConfigSchema = exports_external.object({
   defaultConcurrency: exports_external.number().min(1).optional(),
   providerConcurrency: exports_external.record(exports_external.string(), exports_external.number().min(0)).optional(),
@@ -15794,7 +15808,13 @@ var BackgroundTaskConfigSchema = exports_external.object({
   staleTimeoutMs: exports_external.number().min(60000).optional(),
   messageStalenessTimeoutMs: exports_external.number().min(60000).optional(),
   maxToolCalls: exports_external.number().int().min(10).optional(),
-  circuitBreaker: CircuitBreakerConfigSchema.optional()
+  circuitBreaker: CircuitBreakerConfigSchema.optional(),
+  admissionTimeoutMs: exports_external.union([exports_external.literal(0), exports_external.number().min(60000)]).optional(),
+  nestedAdmission: NestedAdmissionConfigSchema.optional(),
+  wakeScheduler: WakeSchedulerConfigSchema.optional(),
+  jobBoard: JobBoardConfigSchema.optional(),
+  wallClockTimeoutMs: exports_external.union([exports_external.literal(0), exports_external.number().int().min(60000).max(2147483647)]).optional(),
+  wallClockAbortGraceMs: exports_external.number().int().min(1000).max(60000).optional()
 });
 
 // src/config/schema/browser-automation.ts
@@ -15873,7 +15893,7 @@ var CommentCheckerConfigSchema = exports_external.object({
 var ContextModeConfigSchema = exports_external.object({
   enabled: exports_external.boolean().default(true),
   enforce: exports_external.boolean().default(false),
-  blocked_tools: exports_external.array(exports_external.string()).default(["read", "grep", "glob"])
+  blocked_tools: exports_external.array(exports_external.string()).default(["grep", "glob"])
 });
 
 // src/config/schema/dcp.ts
@@ -15959,12 +15979,37 @@ var BUILTIN_DCP_PROFILES = {
     turnProtection: { enabled: true, turns: 5 },
     experimental: { allowSubAgents: true },
     strategies: { purgeErrors: { turns: 4 } }
+  },
+  brutal: {
+    pruneNotification: "off",
+    compress: {
+      maxContextLimit: "15%",
+      minContextLimit: "10%",
+      nudgeFrequency: 1,
+      nudgeForce: "strong",
+      iterationNudgeThreshold: 1
+    },
+    turnProtection: { enabled: false },
+    experimental: { allowSubAgents: false },
+    strategies: { purgeErrors: { turns: 1 } }
   }
 };
+var DcpHandoffCompressionSchema = exports_external.object({
+  enabled: exports_external.boolean().default(true),
+  maxMessages: exports_external.number().int().min(1).default(6),
+  keepFirst: exports_external.number().int().min(0).default(2),
+  keepLast: exports_external.number().int().min(0).default(3)
+});
 var DcpConfigSchema = exports_external.object({
   enabled: exports_external.boolean().default(true),
   profiles: exports_external.record(exports_external.string(), DcpProfileDefinitionSchema).default(BUILTIN_DCP_PROFILES),
   default_profile: exports_external.string().optional(),
+  handoffCompression: DcpHandoffCompressionSchema.default({
+    enabled: true,
+    maxMessages: 6,
+    keepFirst: 2,
+    keepLast: 3
+  }),
   base: exports_external.object({
     autoUpdate: exports_external.boolean().default(false),
     debug: exports_external.boolean().default(false),
@@ -16021,7 +16066,8 @@ var DcpConfigSchema = exports_external.object({
       enabled: false,
       automaticStrategies: true
     }),
-    protectedFilePatterns: exports_external.array(exports_external.string()).default([])
+    protectedFilePatterns: exports_external.array(exports_external.string()).default([]),
+    experimental: DcpExperimentalSchema.default({ allowSubAgents: true })
   }).default({
     autoUpdate: false,
     debug: false,
@@ -16042,7 +16088,8 @@ var DcpConfigSchema = exports_external.object({
     },
     commands: { enabled: true, protectedTools: [] },
     manualMode: { enabled: false, automaticStrategies: true },
-    protectedFilePatterns: []
+    protectedFilePatterns: [],
+    experimental: { allowSubAgents: true }
   })
 });
 

package/dist/config/schema/background-task.d.ts

@@ -1,4 +1,18 @@
 import { z } from "zod";
+/** Idle-parent wake scheduler settings (default ON, default interval 300000ms, minimum 60000ms) */
+export declare const WakeSchedulerConfigSchema: z.ZodObject<{
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    intervalMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/** Job-board snapshot settings (defaults: enabled true, strategy "latest", maxRetainedSnapshots 20) */
+export declare const JobBoardConfigSchema: z.ZodObject<{
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    strategy: z.ZodOptional<z.ZodEnum<{
+        latest: "latest";
+        "checkpoint-compatible": "checkpoint-compatible";
+    }>>;
+    maxRetainedSnapshots: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
 export declare const BackgroundTaskConfigSchema: z.ZodObject<{
     defaultConcurrency: z.ZodOptional<z.ZodNumber>;
     providerConcurrency: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
@@ -11,5 +25,28 @@ export declare const BackgroundTaskConfigSchema: z.ZodObject<{
         maxToolCalls: z.ZodOptional<z.ZodNumber>;
         consecutiveThreshold: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
+    admissionTimeoutMs: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<0>, z.ZodNumber]>>;
+    nestedAdmission: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        mode: z.ZodOptional<z.ZodEnum<{
+            bypass: "bypass";
+            reserve: "reserve";
+        }>>;
+        maxDepth: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    wakeScheduler: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        intervalMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    jobBoard: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        strategy: z.ZodOptional<z.ZodEnum<{
+            latest: "latest";
+            "checkpoint-compatible": "checkpoint-compatible";
+        }>>;
+        maxRetainedSnapshots: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    wallClockTimeoutMs: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<0>, z.ZodNumber]>>;
+    wallClockAbortGraceMs: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export type BackgroundTaskConfig = z.infer<typeof BackgroundTaskConfigSchema>;

package/dist/config/schema/dcp.d.ts

@@ -158,7 +158,44 @@ export declare const BUILTIN_DCP_PROFILES: {
             };
         };
     };
+    readonly brutal: {
+        readonly pruneNotification: "off";
+        readonly compress: {
+            readonly maxContextLimit: "15%";
+            readonly minContextLimit: "10%";
+            readonly nudgeFrequency: 1;
+            readonly nudgeForce: "strong";
+            readonly iterationNudgeThreshold: 1;
+        };
+        readonly turnProtection: {
+            readonly enabled: false;
+        };
+        readonly experimental: {
+            readonly allowSubAgents: false;
+        };
+        readonly strategies: {
+            readonly purgeErrors: {
+                readonly turns: 1;
+            };
+        };
+    };
 };
+/**
+ * Configuration for compressing background task results when sending
+ * completion notifications to the parent session (handoff boundary).
+ *
+ * When enabled, assistant messages beyond `maxMessages` are truncated:
+ * the first `keepFirst` and last `keepLast` messages are preserved,
+ * with a "[... N messages truncated]" marker inserted between them.
+ * This reduces the context cost of notifying the parent session.
+ */
+export declare const DcpHandoffCompressionSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    maxMessages: z.ZodDefault<z.ZodNumber>;
+    keepFirst: z.ZodDefault<z.ZodNumber>;
+    keepLast: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export type DcpHandoffCompression = z.infer<typeof DcpHandoffCompressionSchema>;
 export declare const DcpConfigSchema: z.ZodObject<{
     enabled: z.ZodDefault<z.ZodBoolean>;
     profiles: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
@@ -194,6 +231,12 @@ export declare const DcpConfigSchema: z.ZodObject<{
         }, z.core.$strip>>;
     }, z.core.$strip>>>;
     default_profile: z.ZodOptional<z.ZodString>;
+    handoffCompression: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        maxMessages: z.ZodDefault<z.ZodNumber>;
+        keepFirst: z.ZodDefault<z.ZodNumber>;
+        keepLast: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
     base: z.ZodDefault<z.ZodObject<{
         autoUpdate: z.ZodDefault<z.ZodBoolean>;
         debug: z.ZodDefault<z.ZodBoolean>;
@@ -240,6 +283,9 @@ export declare const DcpConfigSchema: z.ZodObject<{
             automaticStrategies: z.ZodDefault<z.ZodBoolean>;
         }, z.core.$strip>>;
         protectedFilePatterns: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        experimental: z.ZodDefault<z.ZodObject<{
+            allowSubAgents: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type DcpConfig = z.infer<typeof DcpConfigSchema>;

package/dist/config/schema/matrixx-config.d.ts

@@ -1608,6 +1608,12 @@ export declare const MatrixxConfigSchema: z.ZodObject<{
             }, z.core.$strip>>;
         }, z.core.$strip>>>;
         default_profile: z.ZodOptional<z.ZodString>;
+        handoffCompression: z.ZodDefault<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            maxMessages: z.ZodDefault<z.ZodNumber>;
+            keepFirst: z.ZodDefault<z.ZodNumber>;
+            keepLast: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>;
         base: z.ZodDefault<z.ZodObject<{
             autoUpdate: z.ZodDefault<z.ZodBoolean>;
             debug: z.ZodDefault<z.ZodBoolean>;
@@ -1654,6 +1660,9 @@ export declare const MatrixxConfigSchema: z.ZodObject<{
                 automaticStrategies: z.ZodDefault<z.ZodBoolean>;
             }, z.core.$strip>>;
             protectedFilePatterns: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            experimental: z.ZodDefault<z.ZodObject<{
+                allowSubAgents: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strip>>;
         }, z.core.$strip>>;
     }, z.core.$strip>>;
     auto_update: z.ZodOptional<z.ZodBoolean>;
@@ -1701,6 +1710,29 @@ export declare const MatrixxConfigSchema: z.ZodObject<{
             maxToolCalls: z.ZodOptional<z.ZodNumber>;
             consecutiveThreshold: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>>;
+        admissionTimeoutMs: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<0>, z.ZodNumber]>>;
+        nestedAdmission: z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodOptional<z.ZodBoolean>;
+            mode: z.ZodOptional<z.ZodEnum<{
+                bypass: "bypass";
+                reserve: "reserve";
+            }>>;
+            maxDepth: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        wakeScheduler: z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodOptional<z.ZodBoolean>;
+            intervalMs: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        jobBoard: z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodOptional<z.ZodBoolean>;
+            strategy: z.ZodOptional<z.ZodEnum<{
+                latest: "latest";
+                "checkpoint-compatible": "checkpoint-compatible";
+            }>>;
+            maxRetainedSnapshots: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        wallClockTimeoutMs: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<0>, z.ZodNumber]>>;
+        wallClockAbortGraceMs: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
     notification: z.ZodOptional<z.ZodObject<{
         force_enable: z.ZodOptional<z.ZodBoolean>;

package/dist/features/background-agent/admission.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Whether a background launch originates from the root session or from a
+ * managed (subagent) session descended from it. Nested launches are exempt
+ * from the concurrency semaphore so a saturated managed child cannot deadlock
+ * by waiting on its own background work.
+ */
+export type AdmissionClass = {
+    kind: "root";
+} | {
+    kind: "nested";
+    depth: number;
+};
+/**
+ * Classify a launch whose requesting session is `parentSessionID`.
+ *
+ * Walks the child→parent session registry using `getParentSessionID`, treating
+ * each registered ancestor hop as one level of nesting. Depth is capped at
+ * `maxDepth` and reported as actually reached.
+ *
+ * Fails open to `root` when the requester is absent from the process-local
+ * registry (undefined, empty, or unregistered), so a cold start can never
+ * misclassify a root launch as nested.
+ */
+export declare function classifyAdmission(parentSessionID: string | undefined, maxDepth: number): AdmissionClass;

package/dist/features/background-agent/concurrency.d.ts

@@ -1,11 +1,20 @@
 import type { BackgroundTaskConfig } from "../../config/schema";
+export type AcquireOutcome = {
+    granted: true;
+} | {
+    granted: false;
+    reason: "timeout" | "cancelled";
+    waitedMs: number;
+};
 export declare class ConcurrencyManager {
     private config?;
     private counts;
     private queues;
     constructor(config?: BackgroundTaskConfig);
     getConcurrencyLimit(model: string): number;
+    private tryAcquireSlot;
     acquire(model: string): Promise<void>;
+    acquireWithDeadline(model: string, timeoutMs?: number): Promise<AcquireOutcome>;
     release(model: string): void;
     /**
      * Cancel all waiting acquires for a model. Used during cleanup.

package/dist/features/background-agent/constants.d.ts

@@ -12,6 +12,19 @@ export declare const MIN_IDLE_TIME_MS = 5000;
 export declare const POLLING_INTERVAL_MS = 3000;
 export declare const PRUNE_THROTTLE_MS = 30000;
 export declare const TASK_CLEANUP_DELAY_MS: number;
+export declare const DEFAULT_ADMISSION_TIMEOUT_MS = 0;
+export declare const DEFAULT_WALL_CLOCK_TIMEOUT_MS = 0;
+export declare const DEFAULT_WALL_CLOCK_ABORT_GRACE_MS = 5000;
+export declare const DEFAULT_NESTED_ADMISSION_ENABLED = true;
+export declare const DEFAULT_NESTED_ADMISSION_MODE: "bypass";
+export declare const DEFAULT_NESTED_MAX_DEPTH = 2;
+export declare const DEFAULT_WAKE_SCHEDULER_ENABLED = true;
+export declare const DEFAULT_WAKE_INTERVAL_MS = 300000;
+export declare const MIN_WAKE_INTERVAL_MS = 60000;
+export declare const DEFAULT_JOB_BOARD_ENABLED = true;
+export declare const DEFAULT_JOB_BOARD_STRATEGY: "latest";
+export declare const DEFAULT_MAX_RETAINED_SNAPSHOTS = 20;
+export declare const RECONCILE_CONFIRMATION_GRACE_MS = 5000;
 export type ProcessCleanupEvent = NodeJS.Signals | "beforeExit" | "exit";
 export type OpencodeClient = PluginInput["client"];
 export interface MessagePartInfo {

package/dist/features/background-agent/handle-index.d.ts

@@ -26,7 +26,19 @@ export declare const BgHandleSchema: z.ZodObject<{
         pending: "pending";
         running: "running";
         completed: "completed";
+        stopped: "stopped";
+        statusUncertain: "statusUncertain";
     }>;
+    sessionID: z.ZodOptional<z.ZodString>;
+    terminalReason: z.ZodOptional<z.ZodEnum<{
+        aborted: "aborted";
+        "queue-saturated": "queue-saturated";
+        "no-output": "no-output";
+        uncertain: "uncertain";
+        stale: "stale";
+        "nested-depth-exceeded": "nested-depth-exceeded";
+        "wall-clock-timeout": "wall-clock-timeout";
+    }>>;
     model: z.ZodOptional<z.ZodObject<{
         providerID: z.ZodString;
         modelID: z.ZodString;

package/dist/features/background-agent/manager.d.ts

@@ -1,7 +1,7 @@
 import type { PluginInput } from "@opencode-ai/plugin";
-import type { BackgroundTaskConfig, TmuxConfig } from "../../config/schema";
+import type { BackgroundTaskConfig, DcpHandoffCompression, TmuxConfig } from "../../config/schema";
 import { TaskHistory } from "./task-history";
-import type { BackgroundTask, LaunchInput, ResumeInput } from "./types";
+import type { BackgroundTask, LaunchInput, ResumeInput, ReviveInput } from "./types";
 export interface EventProperties {
     sessionID?: string;
     info?: {
@@ -41,15 +41,26 @@ export declare class BackgroundManager {
     private processingKeys;
     private completionTimers;
     private idleDeferralTimers;
+    private wakeScheduler;
     private notificationQueueByParent;
     private enableParentSessionNotifications;
     private cachedCircuitBreakerSettings?;
+    private handoffCompression?;
+    /** Active nested bypass admits per concurrency key (maxDepth cap). */
+    private nestedActive;
+    /** Task IDs admitted via nested bypass — used to decrement `nestedActive` exactly once. */
+    private nestedBypassTaskIds;
+    /** Elapsed-time bound supervisor (U7 wall-clock). OFF by default — arms nothing when disabled. */
+    private wallclock;
+    /** Grace timers pending a terminal wall-clock mark, keyed by task id. */
+    private wallclockGraceTimers;
     readonly taskHistory: TaskHistory;
     constructor(ctx: PluginInput, config?: BackgroundTaskConfig, options?: {
         tmuxConfig?: TmuxConfig;
         onSubagentSessionCreated?: OnSubagentSessionCreated;
         onShutdown?: () => void;
         enableParentSessionNotifications?: boolean;
+        handoffCompression?: DcpHandoffCompression;
     });
     /**
      * Persist a lightweight handle for the given task. Called on running and
@@ -57,14 +68,45 @@ export declare class BackgroundManager {
      * Best-effort: write failures are logged and never break task lifecycle.
      */
     private persistHandle;
+    private armWallclock;
+    private disarmWallclock;
+    private onWallclockFire;
+    private completeWallclockTimeout;
     /**
      * Recover handles persisted by a previous manager/process. Sweeps stale
-     * handles first, then loads the remainder into memory. Running handles are
-     * marked `"interrupt"` (C6) and no concurrency is re-acquired (C7).
+     * handles first, then loads the remainder into memory. Persisted
+     * `running|pending` handles are reconciled against the live host instead of
+     * being flattened to a false `"interrupt"` (C6). No concurrency is
+     * re-acquired for restored running handles (C7).
      */
     restoreHandles(): Promise<void>;
+    /**
+     * Probe the live host for a persisted in-flight handle and apply the
+     * reconciled outcome. Never throws: any unexpected failure degrades to
+     * `statusUncertain`, never a false completion. `restoreHandles()`'s caller
+     * is fire-and-forget (`create-managers.ts`), so rejection is not an option.
+     */
+    private reconcileRestoredTask;
     launch(input: LaunchInput): Promise<BackgroundTask>;
     private processKey;
+    /**
+     * Admit a nested launch. Bypass mode grants immediately without touching the
+     * semaphore; reserve mode first tries the reserved slot with a bounded wait
+     * and falls back to bypass overflow. Both modes enforce the maxDepth cap.
+     * Returns "skip" when the item was terminated (depth exceeded / cancelled).
+     */
+    private admitNested;
+    /**
+     * Terminal `stopped` outcome for a queued task that was never admitted.
+     * Mirrors the cancelTask terminal+notify sequence but never releases a slot
+     * (none was taken) and routes through the same parent-notification pipeline.
+     */
+    private terminateQueuedTask;
+    /**
+     * Decrement the nested bypass count for a task exactly once. Idempotent:
+     * repeated calls after the first are no-ops and can never underflow.
+     */
+    private decrementNestedActive;
     private startTask;
     getTask(id: string): BackgroundTask | undefined;
     getTasksByParentSession(sessionID: string): BackgroundTask[];
@@ -85,6 +127,17 @@ export declare class BackgroundManager {
         concurrencyKey?: string;
     }): Promise<BackgroundTask>;
     resume(input: ResumeInput): Promise<BackgroundTask>;
+    /** Revive a terminal task with a new prompt, from memory or disk. Bounded admission; saturated queue fails truthfully. */
+    revive(input: ReviveInput): Promise<BackgroundTask>;
+    /** Revivable terminal tasks: in-memory first (wins on taskId), then disk; newest-first. */
+    listRevivable(parentSessionID?: string): Array<{
+        taskId: string;
+        description: string;
+        agent: string;
+        status: string;
+        sessionID: string;
+        terminalReason?: string;
+    }>;
     private checkSessionTodos;
     handleEvent(event: Event): void;
     markForNotification(task: BackgroundTask): void;
@@ -100,6 +153,7 @@ export declare class BackgroundManager {
     /**
      * Validates that a session has actual assistant/tool output before marking complete.
      * Prevents premature completion when session.idle fires before agent responds.
+     * Delegates to the shared `session-output` helper (also used by reconciliation).
      */
     private validateSessionHasOutput;
     private clearNotificationsForTask;
@@ -108,6 +162,7 @@ export declare class BackgroundManager {
      * Cleans up the parent entry if no pending tasks remain.
      */
     private cleanupPendingByParent;
+    private refreshParentWake;
     /**
      * Fire-and-forget session abort. Logs failures at debug level instead of
      * swallowing errors silently — useful for diagnosing zombie sessions.

package/dist/features/background-agent/notification-builder.d.ts

@@ -15,3 +15,4 @@ export declare function resolveAgentAndModel(client: {
         modelID: string;
     } | undefined;
 }>;
+export declare function buildJobBoardNotification(snapshot: import("./task-history").JobBoardSnapshot): string;

package/dist/features/background-agent/reconcile.d.ts

@@ -0,0 +1,33 @@
+import type { BgHandle } from "./handle-index";
+import type { BackgroundTerminalReason } from "./types";
+export type ReconcileOutcome = {
+    status: "completed" | "error" | "running" | "stopped" | "statusUncertain";
+    terminalReason?: BackgroundTerminalReason;
+};
+export interface ReconcileProbeClient {
+    session: {
+        status: () => Promise<unknown>;
+        messages: (args: {
+            path: {
+                id: string;
+            };
+        }) => Promise<unknown>;
+        todo: (args: {
+            path: {
+                id: string;
+            };
+        }) => Promise<unknown>;
+    };
+}
+export interface ReconcileDeps {
+    validateOutput?: (sessionID: string) => Promise<boolean>;
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Classify a persisted `running|pending` handle against the live host.
+ *
+ * Deterministic order: unprobeable → uncertain; non-idle → running; recorded
+ * error → error; awaiting-user → running; no output → stopped; output with
+ * incomplete todos → running; otherwise completed. Never throws.
+ */
+export declare function reconcileHandle(client: ReconcileProbeClient, handle: BgHandle, deps?: ReconcileDeps): Promise<ReconcileOutcome>;

package/dist/features/background-agent/revive.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Revive eligibility classification for background tasks.
+ *
+ * Pure logic: decides whether a persisted handle may be revived into a new
+ * session. No I/O, no manager access, no client imports.
+ */
+import type { BgHandle } from "./handle-index";
+import type { BackgroundTask } from "./types";
+export declare const REVIVABLE_STATUSES: readonly ["cancelled", "stopped", "interrupt", "error", "completed"];
+export declare function isRevivableStatus(status: string): boolean;
+export type ReviveBlockReason = "active" | "uncertain" | "no-session" | "unknown-task" | "expired";
+export type ReviveEligibility = {
+    eligible: true;
+} | {
+    eligible: false;
+    reason: ReviveBlockReason;
+};
+export declare function classifyRevivable(handle: {
+    status: string;
+    sessionID?: string;
+    terminalReason?: string;
+}, opts?: {
+    force?: boolean;
+}): ReviveEligibility;
+/**
+ * Locate a revivable handle by task id or session id. `taskId` wins when
+ * both are supplied. Returns `undefined` when neither matches.
+ */
+export declare function findRevivableHandle(handles: BgHandle[], opts: {
+    taskId?: string;
+    sessionId?: string;
+}): BgHandle | undefined;
+/**
+ * Rehydrate a pre-admission `BackgroundTask` from a persisted handle with a
+ * NEW prompt. Mirrors `restoreTaskFromHandle` except `prompt` comes from the
+ * caller and `status` restarts at `"pending"`; `startedAt` is left unset (it
+ * is assigned on admission) and `completedAt`/`error` are cleared.
+ */
+export declare function toReviveTask(handle: BgHandle, prompt: string): BackgroundTask;

package/dist/features/background-agent/session-output.d.ts

@@ -0,0 +1,40 @@
+export interface SessionOutputClient {
+    session: {
+        messages: (args: {
+            path: {
+                id: string;
+            };
+        }) => Promise<unknown>;
+    };
+}
+interface SessionMessagePart {
+    type?: string;
+    text?: string;
+    content?: string | unknown[];
+}
+export interface SessionMessage {
+    info?: {
+        role?: string;
+        error?: unknown;
+    };
+    parts?: SessionMessagePart[];
+}
+/**
+ * Fetch the raw messages for a session. Throws on transport failure so callers
+ * can decide between fail-open (legacy) and fail-safe (reconciliation).
+ */
+export declare function fetchSessionMessages(client: SessionOutputClient, sessionID: string): Promise<SessionMessage[]>;
+/**
+ * True when the session produced real assistant/tool output with content.
+ * Shared by `validateSessionHasOutput` (manager) and `reconcileHandle`.
+ */
+export declare function messagesHaveAssistantOutput(messages: SessionMessage[], sessionID?: string): boolean;
+/** True when any assistant message carries a recorded provider/abort error. */
+export declare function messagesHaveRecordedError(messages: SessionMessage[]): boolean;
+/**
+ * Validate that a session has actual assistant/tool output before marking
+ * complete. Fail-open: transport errors return true so a flaky lookup cannot
+ * block the existing polling/idle completion path.
+ */
+export declare function validateSessionHasOutput(client: SessionOutputClient, sessionID: string): Promise<boolean>;
+export {};

package/dist/features/background-agent/task-history.d.ts

@@ -1,4 +1,22 @@
 import type { BackgroundTaskStatus } from "./types";
+export type JobBoardStrategy = "latest" | "checkpoint-compatible";
+export interface JobBoardRow {
+    agent: string;
+    category?: string;
+    status: BackgroundTaskStatus;
+    description: string;
+    session?: string;
+}
+export interface JobBoardSnapshot {
+    strategy: JobBoardStrategy;
+    block: string;
+    retained?: string[];
+}
+export interface BuildJobBoardSnapshotOpts {
+    strategy?: JobBoardStrategy;
+    maxRetained?: number;
+    previous?: string[];
+}
 export interface TaskHistoryEntry {
     id: string;
     sessionID?: string;
@@ -15,4 +33,6 @@ export declare class TaskHistory {
     getByParentSession(parentSessionID: string): TaskHistoryEntry[];
     clearSession(parentSessionID: string): void;
     formatForCompaction(parentSessionID: string): string | null;
+    getJobBoardEntries(parentSessionID: string): JobBoardRow[];
+    buildJobBoardSnapshot(parentSessionID: string, opts?: BuildJobBoardSnapshotOpts): JobBoardSnapshot | null;
 }

package/dist/features/background-agent/types.d.ts

@@ -1,4 +1,6 @@
-export type BackgroundTaskStatus = "pending" | "running" | "completed" | "error" | "cancelled" | "interrupt";
+export type BackgroundTaskStatus = "pending" | "running" | "completed" | "error" | "cancelled" | "interrupt" | "stopped" | "statusUncertain";
+/** Why a background task reached a terminal state (persisted on the handle). */
+export type BackgroundTerminalReason = "queue-saturated" | "no-output" | "uncertain" | "aborted" | "stale" | "nested-depth-exceeded" | "wall-clock-timeout";
 export interface ToolCallWindow {
     lastSignature: string;
     consecutiveCount: number;
@@ -54,6 +56,10 @@ export interface BackgroundTask {
     lastMsgCount?: number;
     /** Number of consecutive polls with stable message count */
     stablePolls?: number;
+    /** Why the task reached a terminal state (e.g. stopped/statusUncertain) */
+    terminalReason?: BackgroundTerminalReason;
+    /** Compressed result payload for handoff to parent session (set by tryCompleteTask) */
+    compactedResult?: string;
 }
 export interface LaunchInput {
     description: string;
@@ -90,4 +96,18 @@ export interface ResumeInput {
     parentAgent?: string;
     parentTools?: Record<string, boolean>;
 }
+export interface ReviveInput {
+    taskId?: string;
+    sessionId?: string;
+    prompt: string;
+    parentSessionID: string;
+    parentMessageID: string;
+    parentModel?: {
+        providerID: string;
+        modelID: string;
+    };
+    parentAgent?: string;
+    parentTools?: Record<string, boolean>;
+    force?: boolean;
+}
 export {};