opencode-matrixx 2.6.5 → 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 }
   })
 });
 
@@ -16159,6 +16206,7 @@ var HookNameEnum = exports_external.enum([
   "preemptive-compaction",
   "rules-injector",
   "background-notification",
+  "background-task-blocker",
   "auto-update-checker",
   "startup-toast",
   "keyword-detector",
@@ -16233,11 +16281,14 @@ var ModelFallbackEntrySchema = exports_external.object({
   variant: exports_external.string().optional()
 });
 var complexityDowngradeValueSchema = exports_external.string().refine((s) => {
-  if (s.includes("/")) {
-    const parts = s.split("/");
-    return parts.length === 2 && parts[0].length > 0 && parts[1].length > 0;
-  }
-  return false;
+  if (!s.includes("/"))
+    return false;
+  if (s.startsWith("/") || s.endsWith("/"))
+    return false;
+  if (s.includes("//"))
+    return false;
+  const parts = s.split("/");
+  return parts.length >= 2 && parts.every((p) => p.length > 0);
 }, { message: "Must be <provider>/<model>" });
 var ComplexityDowngradesSchema = exports_external.record(exports_external.string(), exports_external.record(exports_external.string(), complexityDowngradeValueSchema));
 var AgentModelRequirementsSchema = exports_external.object({
@@ -16263,8 +16314,12 @@ var ModelRequirementsSchema = exports_external.object({
 var providerModelSchema = exports_external.string().refine((s) => {
   if (!s.includes("/"))
     return false;
+  if (s.startsWith("/") || s.endsWith("/"))
+    return false;
+  if (s.includes("//"))
+    return false;
   const parts = s.split("/");
-  return parts.length === 2 && parts[0].length > 0 && parts[1].length > 0;
+  return parts.length >= 2 && parts.every((p) => p.length > 0);
 }, { message: "Must be <provider>/<model>" });
 var ModelPresetEntrySchema = exports_external.object({
   model: providerModelSchema,

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/hooks.d.ts

@@ -20,6 +20,7 @@ export declare const HookNameSchema: z.ZodUnion<readonly [z.ZodEnum<{
     "preemptive-compaction": "preemptive-compaction";
     "rules-injector": "rules-injector";
     "background-notification": "background-notification";
+    "background-task-blocker": "background-task-blocker";
     "auto-update-checker": "auto-update-checker";
     "startup-toast": "startup-toast";
     "keyword-detector": "keyword-detector";

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

@@ -93,6 +93,7 @@ export declare const MatrixxConfigSchema: z.ZodObject<{
         "preemptive-compaction": "preemptive-compaction";
         "rules-injector": "rules-injector";
         "background-notification": "background-notification";
+        "background-task-blocker": "background-task-blocker";
         "auto-update-checker": "auto-update-checker";
         "startup-toast": "startup-toast";
         "keyword-detector": "keyword-detector";
@@ -1607,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>;
@@ -1653,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>;
@@ -1700,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/create-hooks.d.ts

@@ -33,6 +33,7 @@ export declare function createHooks(args: {
     thinkingBlockValidator: ReturnType<typeof import("./hooks").createThinkingBlockValidatorHook> | null;
     toolPairValidator: ReturnType<typeof import("./hooks").createToolPairValidatorHook> | null;
     designIntentPreserver: ReturnType<typeof import("./hooks").createDesignIntentPreserverHook> | null;
+    backgroundTaskBlocker: ReturnType<typeof import("./hooks").createBackgroundTaskBlockerHook> | null;
     commentChecker: ReturnType<typeof import("./hooks").createCommentCheckerHooks> | null;
     toolOutputTruncator: ReturnType<typeof import("./hooks").createToolOutputTruncatorHook> | null;
     directoryAgentsInjector: ReturnType<typeof import("./hooks").createDirectoryAgentsInjectorHook> | null;

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

@@ -0,0 +1,75 @@
+import { z } from "zod";
+import type { BackgroundTask } from "./types";
+/**
+ * File-backed handle index for background tasks.
+ *
+ * Mirrors the `task-storage` pattern: one file per handle under a
+ * project-scoped `.matrixx/bg-handles/` directory, written atomically via
+ * `tmp + renameSync`. Only a lightweight index is persisted — prompts,
+ * progress, results, errors and tool-call windows stay ephemeral.
+ *
+ * This lets a freshly-created `BackgroundManager` recover previously-created
+ * `bg_*` handles after a plugin/process restart.
+ */
+export declare const BG_HANDLE_DIR_NAME = "bg-handles";
+export declare const BG_HANDLE_FILE_PREFIX = "bg_";
+export declare const BgHandleSchema: z.ZodObject<{
+    taskId: z.ZodString;
+    parentSessionID: z.ZodString;
+    parentMessageID: z.ZodString;
+    description: z.ZodString;
+    agent: z.ZodString;
+    status: z.ZodEnum<{
+        error: "error";
+        cancelled: "cancelled";
+        interrupt: "interrupt";
+        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;
+        variant: z.ZodOptional<z.ZodString>;
+        temperature: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    category: z.ZodOptional<z.ZodString>;
+    concurrencyGroup: z.ZodOptional<z.ZodString>;
+    queuedAt: z.ZodOptional<z.ZodNumber>;
+    startedAt: z.ZodOptional<z.ZodNumber>;
+    completedAt: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type BgHandle = z.infer<typeof BgHandleSchema>;
+/** Project-scoped handle directory: `<project>/.matrixx/bg-handles`. */
+export declare function getBgHandleDir(directory: string): string;
+/** One file per handle id: `<project>/.matrixx/bg-handles/<taskId>.json`. */
+export declare function getHandlePath(directory: string, taskId: string): string;
+/** Project a full task onto the lightweight, persistable handle index. */
+export declare function toHandle(task: BackgroundTask): BgHandle;
+/**
+ * Atomically persist a handle: write to a temp file then rename into place.
+ * Throws on write failure; callers decide how to surface it.
+ */
+export declare function writeHandle(directory: string, task: BackgroundTask): void;
+/** Read and validate every persisted handle. Invalid/corrupt files are skipped. */
+export declare function readHandles(directory: string): BgHandle[];
+/** Remove the handle file for a task id. Returns true when a file was deleted. */
+export declare function deleteHandleFile(directory: string, taskId: string): boolean;
+/**
+ * Bounded TTL sweep: delete handle files whose most recent timestamp is older
+ * than `ttlMs` (default 30 min). Corrupt/unreadable files are swept too so the
+ * directory cannot grow without bound. Returns the number of files removed.
+ */
+export declare function sweepStaleHandles(directory: string, ttlMs?: number, now?: number): number;

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

@@ -0,0 +1 @@
+export {};

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

@@ -1,4 +1,5 @@
 export { ConcurrencyManager } from "./concurrency";
+export { BG_HANDLE_FILE_PREFIX, type BgHandle, BgHandleSchema, deleteHandleFile, getBgHandleDir, getHandlePath, readHandles, sweepStaleHandles, toHandle, writeHandle, } from "./handle-index";
 export { BackgroundManager, type OnSubagentSessionCreated, type SubagentSessionCreatedEvent } from "./manager";
 export { TaskStateManager } from "./state";
 export { TaskHistory, type TaskHistoryEntry } from "./task-history";

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

@@ -0,0 +1 @@
+export {};

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,18 +41,72 @@ 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
+     * terminal transitions only — never on intermediate progress updates (C8).
+     * 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. 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[];
@@ -73,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;
@@ -88,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;
@@ -96,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>;