opencode-matrixx-v2 1.2.2 → 1.3.1

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

@@ -10,6 +10,12 @@ import type { BackgroundTask } from "./types";
  *
  * This lets a freshly-created `BackgroundManager` recover previously-created
  * `bg_*` handles after a plugin/process restart.
+ *
+ * Stale-handle guard: every handle carries a `generation` counter. Removing a
+ * handle (explicit delete or TTL sweep) bumps a per-task tombstone
+ * (`<taskId>.gen`), and the next write for that id embeds the bumped value.
+ * `readHandle` with an expected generation rejects mismatches, so a handle
+ * captured before removal can never resolve to a new task reusing the id.
  */
 export declare const BG_HANDLE_DIR_NAME = "bg-handles";
 export declare const BG_HANDLE_FILE_PREFIX = "bg_";
@@ -52,21 +58,34 @@ export declare const BgHandleSchema: z.ZodObject<{
     queuedAt: z.ZodOptional<z.ZodNumber>;
     startedAt: z.ZodOptional<z.ZodNumber>;
     completedAt: z.ZodOptional<z.ZodNumber>;
+    generation: z.ZodDefault<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;
+/** Tombstone holding the bumped generation after a handle is removed. Never ends in `.json`, so index scans skip it. */
+export declare function getGenerationPath(directory: string, taskId: string): string;
 /** Single source of truth for the OpenCode subagent session title format. */
 export declare function buildSubagentTitle(description: unknown, agent: unknown, category?: unknown): string;
 /** Project a full task onto the lightweight, persistable handle index. */
 export declare function toHandle(task: BackgroundTask): BgHandle;
+export declare function currentGeneration(directory: string, taskId: string): number;
+export declare function bumpGeneration(directory: string, taskId: string): void;
 /**
  * Atomically persist a handle: write to a temp file then rename into place.
+ * The embedded generation is the current counter for the id, so a handle
+ * recreated after removal carries a strictly greater value than the removed one.
  * Throws on write failure; callers decide how to surface it.
  */
 export declare function writeHandle(directory: string, task: BackgroundTask): void;
+/**
+ * Read one handle by id. When `expectedGeneration` is given, a handle whose
+ * embedded generation differs (stale reference, or a new task reusing the id
+ * after removal) is rejected with a log line and `null` is returned.
+ */
+export declare function readHandle(directory: string, taskId: string, expectedGeneration?: number): BgHandle | null;
 /** 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. */
@@ -77,3 +96,15 @@ export declare function deleteHandleFile(directory: string, taskId: string): boo
  * directory cannot grow without bound. Returns the number of files removed.
  */
 export declare function sweepStaleHandles(directory: string, ttlMs?: number, now?: number): number;
+/**
+ * Single-pass sweep + read: one `readdirSync` and one `readHandleFile` per
+ * handle file. Semantics match `sweepStaleHandles` followed by `readHandles`:
+ * corrupt/unparseable files are swept (never bump generation for them — there
+ * is no taskId), stale or timestamp-less readable handles are swept with a
+ * generation bump, fresh handles are returned. Files swept here never appear
+ * in `handles`. Missing directory yields an empty result without throwing.
+ */
+export declare function sweepAndReadHandles(directory: string, ttlMs?: number, now?: number): {
+    handles: BgHandle[];
+    removed: number;
+};

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

@@ -4,7 +4,7 @@
  * - `hooks/background-task-blocker/` guards tool execution while background tasks run.
  * - `tools/background-task/` exposes agent-callable task controls (cancel/output/revive).
  */
-export { BG_HANDLE_FILE_PREFIX, type BgHandle, BgHandleSchema, deleteHandleFile, getBgHandleDir, getHandlePath, readHandles, sweepStaleHandles, toHandle, writeHandle, } from "./handle-index";
+export { BG_HANDLE_FILE_PREFIX, type BgHandle, BgHandleSchema, deleteHandleFile, getBgHandleDir, getHandlePath, readHandles, sweepAndReadHandles, 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/lifecycle.d.ts

@@ -1,5 +1,5 @@
 import type { NativeDomains } from "../../../shared/session/session-context-source";
-import type { BackgroundTask, LaunchInput, ResumeInput } from "../types";
+import type { BackgroundTask, BackgroundTaskStatus, LaunchInput, ResumeInput } from "../types";
 import type { ManagerRuntime } from "./types";
 /**
  * Task lifecycle: restore, launch, track, resume, prompt.
@@ -8,6 +8,7 @@ import type { ManagerRuntime } from "./types";
  * `BackgroundManager` receiver — same statements, no `this`. Thin
  * delegating methods on `BackgroundManager` preserve the public API.
  */
+export declare function isSettled(status: BackgroundTaskStatus): boolean;
 export declare function restoreHandles(rt: ManagerRuntime): Promise<void>;
 export declare function launchTask(rt: ManagerRuntime, input: LaunchInput & {
     sessionId?: string;

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

@@ -98,6 +98,7 @@ export declare class BackgroundManager implements ManagerRuntime {
     handleEvent(event: V2Event): void;
     getKnownSessionIds(): Set<string>;
     getTask(id: string): BackgroundTask | undefined;
+    persistHandleFenced(task: BackgroundTask, expectedGeneration: number): void;
     getTasksByParentSession(sessionID: string): BackgroundTask[];
     getAllDescendantTasks(sessionID: string): BackgroundTask[];
     getNativeDescendants(sessionId: string): ReturnType<ManagerStore["getNativeDescendants"]>;
@@ -111,7 +112,9 @@ export declare class BackgroundManager implements ManagerRuntime {
     }): Promise<boolean>;
     cancelPendingTask(taskId: string): boolean;
     cancelAllForSession(parentSessionID: string): number;
-    waitForAllDescendants(sessionID: string, timeoutMs?: number, pollIntervalMs?: number): Promise<{
+    waitForAllDescendants(sessionID: string, timeoutMs?: number, pollIntervalMs?: number, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
         completed: Array<{
             id: string;
             description: string;
@@ -125,5 +128,11 @@ export declare class BackgroundManager implements ManagerRuntime {
             status: string;
         }>;
     }>;
+    waiterCount(): number;
+    rejectWaiters(sessionID: string | undefined, err: unknown): void;
     shutdown(): void;
+    shutdownWithDeadline(deadlineMs?: number): {
+        forced: boolean;
+        abandoned: string[];
+    };
 }

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

@@ -2,6 +2,15 @@ import type { V2Event } from "../../../plugin/tool/context";
 import type { BackgroundTask, ReviveInput } from "../types";
 import type { BackgroundManager } from "./manager";
 import type { ManagerRuntime, ResolveAnyResult } from "./types";
+/**
+ * B11 minimal gate: quarantine corrupt handle files before revival.
+ *
+ * Links the B7 error contract (`StorageCorruptError` in task-storage):
+ * unreadable or shape-invalid `bg_*.json` files are renamed aside to
+ * `<name>.corrupt` + logged (never deleted, never crash revival).
+ * Best-effort: individual failures are logged and skipped.
+ */
+export declare function quarantineCorruptHandles(directory: string): number;
 export declare function reviveTask(rt: ManagerRuntime, input: ReviveInput): Promise<BackgroundTask>;
 export declare function listRevivable(rt: ManagerRuntime, parentSessionID?: string): Array<{
     taskId: string;

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

@@ -1,5 +1,7 @@
 import type { BackgroundTaskConfig } from "../../../config/schema";
+import { TaskMap } from "../task-map";
 import type { BackgroundTask } from "../types";
+import { WallclockSupervisor } from "../wallclock";
 import type { NativeDescendant } from "./types";
 /**
  * In-memory task registry behind `BackgroundManager`.
@@ -11,12 +13,18 @@ import type { NativeDescendant } from "./types";
  * store through `ManagerRuntime` — they never touch `BackgroundManager`.
  */
 export declare class ManagerStore {
-    readonly tasks: Map<string, BackgroundTask>;
+    readonly tasks: TaskMap<BackgroundTask>;
     readonly knownSessions: Set<string>;
     readonly nativeDescCache: Map<string, {
         at: number;
         rows: NativeDescendant[];
     }>;
+    readonly wallclock: WallclockSupervisor;
+    readonly pendingSpawns: Set<string>;
+    readonly waiters: Set<{
+        sessionID: string;
+        reject: (err: unknown) => void;
+    }>;
     directory: string;
     config?: BackgroundTaskConfig;
     constructor(directory: string, config?: BackgroundTaskConfig);
@@ -28,6 +36,10 @@ export declare class ManagerStore {
     getNativeDescendants(sessionId: string): NativeDescendant[];
     findBySession(sessionID: string): BackgroundTask | undefined;
     findDiskTaskBySession(sessionID: string): BackgroundTask | undefined;
+    disarmWallclock(taskId: string): void;
     taskTtlMs(): number;
     persistHandle(task: BackgroundTask): void;
+    currentGeneration(taskId: string): number;
+    persistHandleFenced(task: BackgroundTask, expectedGeneration: number): void;
+    bumpTaskGeneration(taskId: string): number;
 }

package/dist/features/background-agent/message-dir.d.ts

@@ -1,4 +1,7 @@
 import { type StoredMessage } from "../context-injection/hook-bridge";
+export declare function isValidSessionID(sessionID: string): boolean;
+export declare function assertValidSessionID(sessionID: string): void;
+export declare function resolveSessionDirPath(baseDir: string, sessionID: string): string;
 export declare function getMessageDir(sessionID: string): string | null;
 export declare function _resetMessageDirCacheForTesting(): void;
 export declare function isCompactionAgent(agent: string | undefined): boolean;

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

@@ -22,6 +22,37 @@ export declare function classifyRevivable(handle: {
 }, opts?: {
     force?: boolean;
 }): ReviveEligibility;
+/**
+ * B11: corrupt-handle predicate (pure, no I/O).
+ *
+ * Links the B7 error contract (`StorageCorruptError` in task-storage):
+ * callers quarantine (rename aside + log, never delete) any value for
+ * which this returns true instead of letting it crash revival. A handle
+ * is corrupt when it is not an object or lacks the required shape
+ * (`taskId` string + recognised `status` string). Unknown statuses are
+ * NOT corrupt — they are ineligible (`unknown-task`) via
+ * `classifyRevivable`, not quarantine candidates.
+ */
+export declare function isCorruptHandleValue(value: unknown): boolean;
+export type ReviveSkip = {
+    handle: BgHandle;
+    reason: ReviveBlockReason;
+};
+/**
+ * B11: partition handles into revivable vs skipped (pure, no I/O).
+ *
+ * Terminal handles WITHOUT a session (`completed`/`error`/`cancelled`
+ * with no `sessionID`) are never resurrected — they land in `skipped`
+ * with reason `no-session`. Active handles (`pending`/`running`) land
+ * in `skipped` with reason `active` (inspect via `background_output`,
+ * not revive). Callers MUST log each skip (reason + taskId).
+ */
+export declare function filterRevivableHandles(handles: BgHandle[], opts?: {
+    force?: boolean;
+}): {
+    eligible: BgHandle[];
+    skipped: ReviveSkip[];
+};
 /**
  * Locate a revivable handle by task id or session id. `taskId` wins when
  * both are supplied. Returns `undefined` when neither matches.
@@ -36,4 +67,27 @@ export declare function findRevivableHandle(handles: BgHandle[], opts: {
  * caller and `status` restarts at `"pending"`; `startedAt` is left unset (it
  * is assigned on admission) and `completedAt`/`error` are cleared.
  */
+export type DeadTargetReason = "expired" | "stale-generation" | "session-dead";
+export declare class DeadReviveTargetError extends Error {
+    kind: "DeadTarget";
+    reason: DeadTargetReason;
+    taskId: string;
+    constructor(taskId: string, reason: DeadTargetReason, detail: string);
+}
+export type ProbeCandidate = {
+    taskId: string;
+    sessionID?: string;
+    generation?: number;
+};
+export type ProbeResult = {
+    alive: true;
+} | {
+    alive: false;
+    reason: DeadTargetReason;
+    error: DeadReviveTargetError;
+};
+export declare function probeReviveTarget(directory: string, candidate: ProbeCandidate, opts?: {
+    expectedGeneration?: number;
+    isSessionLive?: (sessionID: string) => boolean;
+}): ProbeResult;
 export declare function toReviveTask(handle: BgHandle, prompt: string): BackgroundTask;

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

@@ -1,12 +1,12 @@
 import type { QueueItem } from "./constants";
+import { TaskMap } from "./task-map";
 import type { BackgroundTask, LaunchInput } from "./types";
 export declare class TaskStateManager {
-    readonly tasks: Map<string, BackgroundTask>;
+    readonly tasks: TaskMap<BackgroundTask>;
     readonly notifications: Map<string, BackgroundTask[]>;
     readonly pendingByParent: Map<string, Set<string>>;
     readonly queuesByKey: Map<string, QueueItem[]>;
     readonly processingKeys: Set<string>;
-    readonly completionTimers: Map<string, ReturnType<typeof setTimeout>>;
     getTask(id: string): BackgroundTask | undefined;
     findBySession(sessionID: string): BackgroundTask | undefined;
     getTasksByParentSession(sessionID: string): BackgroundTask[];
@@ -27,9 +27,6 @@ export declare class TaskStateManager {
     addToQueue(key: string, item: QueueItem): void;
     getQueue(key: string): QueueItem[] | undefined;
     removeFromQueue(key: string, taskId: string): boolean;
-    setCompletionTimer(taskId: string, timer: ReturnType<typeof setTimeout>): void;
-    clearCompletionTimer(taskId: string): void;
-    clearAllCompletionTimers(): void;
     clear(): void;
     cancelPendingTask(taskId: string): boolean;
 }

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

@@ -0,0 +1,31 @@
+import type { BackgroundTask } from "./types";
+type SessionNormalizer = (sessionID: string) => string;
+/**
+ * Task registry keyed by task id that also maintains secondary indices for the
+ * two lookup shapes the manager performs on every poll/notification:
+ *
+ * - `sessionID -> taskId` (O(1) `bySession`)
+ * - `parentSessionID -> Set<taskId>` (O(k) `byParent`)
+ *
+ * The map stays a `Map` so every existing `set/get/delete/clear/size/values`
+ * call site keeps working. Because tasks are also mutated in place — most
+ * notably `task.sessionID` is assigned after insertion (`manager/lifecycle.ts`)
+ * — mutations raise `dirty`, and a lookup that misses rebuilds once from the
+ * live entries before reporting absence. A hit never pays for a rebuild.
+ */
+export declare class TaskMap<T extends BackgroundTask> extends Map<string, T> {
+    private readonly sessionIndex;
+    private readonly parentIndex;
+    private readonly normalizeSessionID;
+    dirty: boolean;
+    constructor(normalizeSessionID?: SessionNormalizer);
+    set(key: string, task: T): this;
+    delete(key: string): boolean;
+    clear(): void;
+    bySession(sessionID: string): T | undefined;
+    byParent(parentSessionID: string): T[];
+    rebuild(): void;
+    private index;
+    private unindex;
+}
+export {};

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

@@ -50,7 +50,7 @@ export interface BackgroundTask {
     parentTools?: Record<string, boolean>;
     /** Marks if the task was launched from an unstable agent/category */
     isUnstableAgent?: boolean;
-    /** Category used for this task (e.g., 'quick', 'construct') */
+    /** Category used for this task (e.g., 'bullet-time', 'construct') */
     category?: string;
     /** Last message count for stability detection */
     lastMsgCount?: number;
@@ -60,6 +60,8 @@ export interface BackgroundTask {
     terminalReason?: BackgroundTerminalReason;
     /** Compressed result payload for handoff to parent session (set by tryCompleteTask) */
     compactedResult?: string;
+    /** Monotonic epoch fencing token: bumped on revive/takeover, stale writers are rejected */
+    generation?: number;
 }
 export interface LaunchInput {
     description: string;

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

@@ -1,35 +1,30 @@
-/**
- * Wall-clock supervisor: fire-once elapsed-time bound for running background tasks.
- *
- * Staleness is activity-based; this module is elapsed-time-based. Each armed entry
- * fires its callback exactly once when `startedAtMs + timeoutMs` passes, no matter
- * how busy or productive the task looks. A timeout of `0` or `undefined` means OFF
- * and arms nothing.
- *
- * Grace contract (manager-owned, pinned here): on fire the manager aborts the
- * session once, waits `wallClockAbortGraceMs`, then marks the task terminal —
- * unless the task completed naturally during grace, in which case the natural
- * outcome wins and the pending mark is cancelled.
- *
- * This module must not import from manager/client/fs — pure timers only. It mirrors
- * the settled-flag lifecycle of `acquireWithDeadline` in `concurrency.ts`.
- */
-/** Maximum delay accepted by `setTimeout` (2^31-1 ms); enforced by schema max too. */
 export declare const MAX_WALLCLOCK_TIMEOUT_MS = 2147483647;
-/** Context delivered to the fire callback exactly once per armed deadline. */
 export interface WallclockFireContext {
     taskId: string;
     elapsedMs: number;
     limitMs: number;
 }
 export type WallclockFireCallback = (ctx: WallclockFireContext) => void;
-/** Pure remaining-time math: deadline minus now (negative when already expired). */
+export interface WallclockPersistedDeadline {
+    deadlineMono: number;
+    wallStart: number;
+    limitMs: number;
+}
+export interface WallclockClock {
+    nowWall?: () => number;
+    nowMono?: () => number;
+}
 export declare function remainingMs(startedAtMs: number, timeoutMs: number, nowMs?: number): number;
-/** OFF (`0`/`undefined`) never arms; any other value is an active elapsed-time bound. */
+export declare function remainingMono(deadlineMono: number, nowMono: number): number;
 export declare function isWallclockEnabled(timeoutMs: number | undefined): timeoutMs is number;
 export declare class WallclockSupervisor {
     private entries;
+    private readonly nowWall;
+    private readonly nowMono;
+    constructor(clock?: WallclockClock);
     arm(taskId: string, startedAtMs: number, timeoutMs: number | undefined, onFire: WallclockFireCallback): void;
+    resume(taskId: string, persisted: WallclockPersistedDeadline, onFire: WallclockFireCallback): void;
+    snapshot(taskId: string): WallclockPersistedDeadline | undefined;
     disarm(taskId: string): boolean;
     disarmAll(): void;
     size(): number;

package/dist/features/builtin-commands/templates/end-redpill.d.ts

@@ -0,0 +1 @@
+export declare const END_REDPILL_TEMPLATE = "Deactivate redpill mode for the current session.\n\nThis command will:\n1. Remove the <redpill-mode> rules block from the active context\n2. Restore default Matrixx behavior (no enforced certainty protocol, no mandatory plan agent, no required acceptance criteria)\n3. Stop redpill-specific parallel delegation pressure\n\nAfter running this command:\n- The session continues with normal Matrixx rules\n- Existing todos and plans remain unchanged\n- Already-spawned background tasks continue to completion\n- The deactivation is per-session and clears when the session ends\n\nUse this when you want to exit redpill mode explicitly and return to standard behavior. Useful for sub-tasks that should not inherit redpill rules, or when switching from heavy-execution to lighter reasoning.";

package/dist/features/builtin-commands/templates/init-deep.d.ts

@@ -1 +1 @@
-export declare const INIT_DEEP_TEMPLATE = "# /init-deep\n\nGenerate hierarchical AGENTS.md files. Root + complexity-scored subdirectories.\n\n## Usage\n\n```\n/init-deep                      # Update mode: modify existing + create new where warranted\n/init-deep --create-new         # Read existing \u2192 remove all \u2192 regenerate from scratch\n/init-deep --max-depth=2        # Limit directory depth (default: 3)\n```\n\n---\n\n## Workflow (High-Level)\n\n1. **Discovery + Analysis** (concurrent)\n   - Fire background explore agents immediately\n   - Main session: bash structure + LSP codemap + read existing AGENTS.md\n2. **Score & Decide** - Determine AGENTS.md locations from merged findings\n3. **Generate** - Root first, then subdirs in parallel\n4. **Review** - Deduplicate, trim, validate\n\n<critical>\n**task_create ALL phases. Mark in_progress \u2192 completed in real-time.**\n```\ntask_create({ items: [\n  { subject: \"discovery\", priority: \"high\", description: \"Fire explore agents + LSP codemap + read existing\" },\n  { subject: \"scoring\", priority: \"high\", description: \"Score directories, determine locations\" },\n  { subject: \"generate\", priority: \"high\", description: \"Generate AGENTS.md files (root + subdirs)\" },\n  { subject: \"review\", priority: \"medium\", description: \"Deduplicate, validate, trim\" }\n]})\n```\n</critical>\n\n---\n\n## Phase 1: Discovery + Analysis (Concurrent)\n\n**Mark \"discovery\" as in_progress.**\n\n### Fire Background Explore Agents IMMEDIATELY\n\nDon't wait\u2014these run async while main session works.\n\n```\n// Fire all at once, collect results later\ntask(subagent_type=\"trinity\", load_skills=[], description=\"Explore project structure\", run_in_background=true, prompt=\"Project structure: PREDICT standard patterns for detected language \u2192 REPORT deviations only\")\ntask(subagent_type=\"trinity\", load_skills=[], description=\"Find entry points\", run_in_background=true, prompt=\"Entry points: FIND main files \u2192 REPORT non-standard organization\")\ntask(subagent_type=\"trinity\", load_skills=[], description=\"Find conventions\", run_in_background=true, prompt=\"Conventions: FIND config files (.eslintrc, pyproject.toml, .editorconfig) \u2192 REPORT project-specific rules\")\ntask(subagent_type=\"trinity\", load_skills=[], description=\"Find anti-patterns\", run_in_background=true, prompt=\"Anti-patterns: FIND 'DO NOT', 'NEVER', 'ALWAYS', 'DEPRECATED' comments \u2192 LIST forbidden patterns\")\ntask(subagent_type=\"trinity\", load_skills=[], description=\"Explore build/CI\", run_in_background=true, prompt=\"Build/CI: FIND .github/workflows, Makefile \u2192 REPORT non-standard patterns\")\ntask(subagent_type=\"trinity\", load_skills=[], description=\"Find test patterns\", run_in_background=true, prompt=\"Test patterns: FIND test configs, test structure \u2192 REPORT unique conventions\")\n```\n\n<dynamic-agents>\n**DYNAMIC AGENT SPAWNING**: After bash analysis, spawn ADDITIONAL explore agents based on project scale:\n\n| Factor | Threshold | Additional Agents |\n|--------|-----------|-------------------|\n| **Total files** | >100 | +1 per 100 files |\n| **Total lines** | >10k | +1 per 10k lines |\n| **Directory depth** | \u22654 | +2 for deep exploration |\n| **Large files (>500 lines)** | >10 files | +1 for complexity hotspots |\n| **Monorepo** | detected | +1 per package/workspace |\n| **Multiple languages** | >1 | +1 per language |\n\n```bash\n# Measure project scale first\ntotal_files=$(find . -type f -not -path '*/node_modules/*' -not -path '*/.git/*' | wc -l)\ntotal_lines=$(find . -type f \\( -name \"*.ts\" -o -name \"*.py\" -o -name \"*.go\" \\) -not -path '*/node_modules/*' -exec wc -l {} + 2>/dev/null | tail -1 | awk '{print $1}')\nlarge_files=$(find . -type f \\( -name \"*.ts\" -o -name \"*.py\" \\) -not -path '*/node_modules/*' -exec wc -l {} + 2>/dev/null | awk '$1 > 500 {count++} END {print count+0}')\nmax_depth=$(find . -type d -not -path '*/node_modules/*' -not -path '*/.git/*' | awk -F/ '{print NF}' | sort -rn | head -1)\n```\n\nExample spawning:\n```\n// 500 files, 50k lines, depth 6, 15 large files \u2192 spawn 5+5+2+1 = 13 additional agents\ntask(subagent_type=\"trinity\", load_skills=[], description=\"Analyze large files\", run_in_background=true, prompt=\"Large file analysis: FIND files >500 lines, REPORT complexity hotspots\")\ntask(subagent_type=\"trinity\", load_skills=[], description=\"Explore deep modules\", run_in_background=true, prompt=\"Deep modules at depth 4+: FIND hidden patterns, internal conventions\")\ntask(subagent_type=\"trinity\", load_skills=[], description=\"Find shared utilities\", run_in_background=true, prompt=\"Cross-cutting concerns: FIND shared utilities across directories\")\n// ... more based on calculation\n```\n</dynamic-agents>\n\n### Main Session: Concurrent Analysis\n\n**While background agents run**, main session does:\n\n#### 1. Bash Structural Analysis\n```bash\n# Directory depth + file counts\nfind . -type d -not -path '*/\\.*' -not -path '*/node_modules/*' -not -path '*/venv/*' -not -path '*/dist/*' -not -path '*/build/*' | awk -F/ '{print NF-1}' | sort -n | uniq -c\n\n# Files per directory (top 30)\nfind . -type f -not -path '*/\\.*' -not -path '*/node_modules/*' | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn | head -30\n\n# Code concentration by extension\nfind . -type f \\( -name \"*.py\" -o -name \"*.ts\" -o -name \"*.tsx\" -o -name \"*.js\" -o -name \"*.go\" -o -name \"*.rs\" \\) -not -path '*/node_modules/*' | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn | head -20\n\n# Existing AGENTS.md / CLAUDE.md\nfind . -type f \\( -name \"AGENTS.md\" -o -name \"CLAUDE.md\" \\) -not -path '*/node_modules/*' 2>/dev/null\n```\n\n#### 2. Read Existing AGENTS.md\n```\nFor each existing file found:\n  Read(filePath=file)\n  Extract: key insights, conventions, anti-patterns\n  Store in EXISTING_AGENTS map\n```\n\nIf `--create-new`: Read all existing first (preserve context) \u2192 then delete all \u2192 regenerate.\n\n#### 3. LSP Codemap (if available)\n```\nLspServers()  # Check availability\n\n# Entry points (parallel)\nLspDocumentSymbols(filePath=\"src/index.ts\")\nLspDocumentSymbols(filePath=\"main.py\")\n\n# Key symbols (parallel)\nLspWorkspaceSymbols(filePath=\".\", query=\"class\")\nLspWorkspaceSymbols(filePath=\".\", query=\"interface\")\nLspWorkspaceSymbols(filePath=\".\", query=\"function\")\n\n# Centrality for top exports\nLspFindReferences(filePath=\"...\", line=X, character=Y)\n```\n\n**LSP Fallback**: If unavailable, rely on explore agents + AST-grep.\n\n### Collect Background Results\n\n```\n// After main session analysis done, collect all task results\nfor each task_id: background_output(task_id=\"...\")\n```\n\n**Merge: bash + LSP + existing + explore findings. Mark \"discovery\" as completed.**\n\n---\n\n## Phase 2: Scoring & Location Decision\n\n**Mark \"scoring\" as in_progress.**\n\n### Scoring Matrix\n\n| Factor | Weight | High Threshold | Source |\n|--------|--------|----------------|--------|\n| File count | 3x | >20 | bash |\n| Subdir count | 2x | >5 | bash |\n| Code ratio | 2x | >70% | bash |\n| Unique patterns | 1x | Has own config | explore |\n| Module boundary | 2x | Has index.ts/__init__.py | bash |\n| Symbol density | 2x | >30 symbols | LSP |\n| Export count | 2x | >10 exports | LSP |\n| Reference centrality | 3x | >20 refs | LSP |\n\n### Decision Rules\n\n| Score | Action |\n|-------|--------|\n| **Root (.)** | ALWAYS create |\n| **>15** | Create AGENTS.md |\n| **8-15** | Create if distinct domain |\n| **<8** | Skip (parent covers) |\n\n### Output\n```\nAGENTS_LOCATIONS = [\n  { path: \".\", type: \"root\" },\n  { path: \"src/hooks\", score: 18, reason: \"high complexity\" },\n  { path: \"src/api\", score: 12, reason: \"distinct domain\" }\n]\n```\n\n**Mark \"scoring\" as completed.**\n\n---\n\n## Phase 3: Generate AGENTS.md\n\n**Mark \"generate\" as in_progress.**\n\n<critical>\n**File Writing Rule**: If AGENTS.md already exists at the target path \u2192 use `Edit` tool. If it does NOT exist \u2192 use `Write` tool.\nNEVER use Write to overwrite an existing file. ALWAYS check existence first via `Read` or discovery results.\n</critical>\n\n### Root AGENTS.md (Full Treatment)\n\n```markdown\n# PROJECT KNOWLEDGE BASE\n\n**Generated:** {TIMESTAMP}\n**Commit:** {SHORT_SHA}\n**Branch:** {BRANCH}\n\n## OVERVIEW\n{1-2 sentences: what + core stack}\n\n## STRUCTURE\n\\`\\`\\`\n{root}/\n\u251C\u2500\u2500 {dir}/    # {non-obvious purpose only}\n\u2514\u2500\u2500 {entry}\n\\`\\`\\`\n\n## WHERE TO LOOK\n| Task | Location | Notes |\n|------|----------|-------|\n\n## CODE MAP\n{From LSP - skip if unavailable or project <10 files}\n\n| Symbol | Type | Location | Refs | Role |\n|--------|------|----------|------|------|\n\n## CONVENTIONS\n{ONLY deviations from standard}\n\n## ANTI-PATTERNS (THIS PROJECT)\n{Explicitly forbidden here}\n\n## UNIQUE STYLES\n{Project-specific}\n\n## COMMANDS\n\\`\\`\\`bash\n{dev/test/build}\n\\`\\`\\`\n\n## NOTES\n{Gotchas}\n```\n\n**Quality gates**: 50-150 lines, no generic advice, no obvious info.\n\n### Subdirectory AGENTS.md (Parallel)\n\nLaunch writing tasks for each location:\n\n```\nfor loc in AGENTS_LOCATIONS (except root):\n  task(category=\"broadcast\", load_skills=[], run_in_background=false, description=\"Generate AGENTS.md\", prompt=\\`\n    Generate AGENTS.md for: ${loc.path}\n    - Reason: ${loc.reason}\n    - 30-80 lines max\n    - NEVER repeat parent content\n    - Sections: OVERVIEW (1 line), STRUCTURE (if >5 subdirs), WHERE TO LOOK, CONVENTIONS (if different), ANTI-PATTERNS\n  \\`)\n```\n\n**Wait for all. Mark \"generate\" as completed.**\n\n---\n\n## Phase 4: Review & Deduplicate\n\n**Mark \"review\" as in_progress.**\n\nFor each generated file:\n- Remove generic advice\n- Remove parent duplicates\n- Trim to size limits\n- Verify telegraphic style\n\n**Mark \"review\" as completed.**\n\n---\n\n## Final Report\n\n```\n=== init-deep Complete ===\n\nMode: {update | create-new}\n\nFiles:\n  [OK] ./AGENTS.md (root, {N} lines)\n  [OK] ./src/hooks/AGENTS.md ({N} lines)\n\nDirs Analyzed: {N}\nAGENTS.md Created: {N}\nAGENTS.md Updated: {N}\n\nHierarchy:\n  ./AGENTS.md\n  \u2514\u2500\u2500 src/hooks/AGENTS.md\n```\n\n---\n\n## Anti-Patterns\n\n- **Static agent count**: MUST vary agents based on project size/depth\n- **Sequential execution**: MUST parallel (explore + LSP concurrent)\n- **Ignoring existing**: ALWAYS read existing first, even with --create-new\n- **Over-documenting**: Not every dir needs AGENTS.md\n- **Redundancy**: Child never repeats parent\n- **Generic content**: Remove anything that applies to ALL projects\n- **Verbose style**: Telegraphic or die";
+export declare const INIT_DEEP_TEMPLATE = "# /init-deep\n\nGenerate hierarchical AGENTS.md files. Root + complexity-scored subdirectories.\n\n## Usage\n\n```\n/init-deep                      # Update mode: modify existing + create new where warranted\n/init-deep --create-new         # Read existing \u2192 remove all \u2192 regenerate from scratch\n/init-deep --max-depth=2        # Limit directory depth (default: 3)\n```\n\n---\n\n## Workflow (High-Level)\n\n1. **Discovery + Analysis** (concurrent)\n   - Fire background explore agents immediately\n   - Main session: bash structure + LSP codemap + read existing AGENTS.md\n2. **Score & Decide** - Determine AGENTS.md locations from merged findings\n3. **Generate** - Root first, then subdirs in parallel\n4. **Review** - Deduplicate, trim, validate\n\n<critical>\n**task_create ALL phases. Mark in_progress \u2192 completed in real-time.**\n```\ntask_create({ items: [\n  { subject: \"discovery\", priority: \"high\", description: \"Fire explore agents + LSP codemap + read existing\" },\n  { subject: \"scoring\", priority: \"high\", description: \"Score directories, determine locations\" },\n  { subject: \"generate\", priority: \"high\", description: \"Generate AGENTS.md files (root + subdirs)\" },\n  { subject: \"review\", priority: \"medium\", description: \"Deduplicate, validate, trim\" }\n]})\n```\n</critical>\n\n---\n\n## Phase 1: Discovery + Analysis (Concurrent)\n\n**Mark \"discovery\" as in_progress.**\n\n### Fire Background Explore Agents IMMEDIATELY\n\nDon't wait\u2014these run async while main session works.\n\n```\n// Fire all at once, collect results later\ntask(subagent_type=\"trinity\", load_skills=[], description=\"Explore project structure\", run_in_background=true, prompt=\"Project structure: PREDICT standard patterns for detected language \u2192 REPORT deviations only\")\ntask(subagent_type=\"trinity\", load_skills=[], description=\"Find entry points\", run_in_background=true, prompt=\"Entry points: FIND main files \u2192 REPORT non-standard organization\")\ntask(subagent_type=\"trinity\", load_skills=[], description=\"Find conventions\", run_in_background=true, prompt=\"Conventions: FIND config files (.eslintrc, pyproject.toml, .editorconfig) \u2192 REPORT project-specific rules\")\ntask(subagent_type=\"trinity\", load_skills=[], description=\"Find anti-patterns\", run_in_background=true, prompt=\"Anti-patterns: FIND 'DO NOT', 'NEVER', 'ALWAYS', 'DEPRECATED' comments \u2192 LIST forbidden patterns\")\ntask(subagent_type=\"trinity\", load_skills=[], description=\"Explore build/CI\", run_in_background=true, prompt=\"Build/CI: FIND .github/workflows, Makefile \u2192 REPORT non-standard patterns\")\ntask(subagent_type=\"trinity\", load_skills=[], description=\"Find test patterns\", run_in_background=true, prompt=\"Test patterns: FIND test configs, test structure \u2192 REPORT unique conventions\")\n```\n\n<dynamic-agents>\n**DYNAMIC AGENT SPAWNING**: After bash analysis, spawn ADDITIONAL explore agents based on project scale:\n\n| Factor | Threshold | Additional Agents |\n|--------|-----------|-------------------|\n| **Total files** | >100 | +1 per 100 files |\n| **Total lines** | >10k | +1 per 10k lines |\n| **Directory depth** | \u22654 | +2 for deep exploration |\n| **Large files (>500 lines)** | >10 files | +1 for complexity hotspots |\n| **Monorepo** | detected | +1 per package/workspace |\n| **Multiple languages** | >1 | +1 per language |\n\n```bash\n# Measure project scale first\ntotal_files=$(find . -type f -not -path '*/node_modules/*' -not -path '*/.git/*' | wc -l)\ntotal_lines=$(find . -type f \\( -name \"*.ts\" -o -name \"*.py\" -o -name \"*.go\" \\) -not -path '*/node_modules/*' -exec wc -l {} + 2>/dev/null | tail -1 | awk '{print $1}')\nlarge_files=$(find . -type f \\( -name \"*.ts\" -o -name \"*.py\" \\) -not -path '*/node_modules/*' -exec wc -l {} + 2>/dev/null | awk '$1 > 500 {count++} END {print count+0}')\nmax_depth=$(find . -type d -not -path '*/node_modules/*' -not -path '*/.git/*' | awk -F/ '{print NF}' | sort -rn | head -1)\n```\n\nExample spawning:\n```\n// 500 files, 50k lines, depth 6, 15 large files \u2192 spawn 5+5+2+1 = 13 additional agents\ntask(subagent_type=\"trinity\", load_skills=[], description=\"Analyze large files\", run_in_background=true, prompt=\"Large file analysis: FIND files >500 lines, REPORT complexity hotspots\")\ntask(subagent_type=\"trinity\", load_skills=[], description=\"Explore deep modules\", run_in_background=true, prompt=\"Deep modules at depth 4+: FIND hidden patterns, internal conventions\")\ntask(subagent_type=\"trinity\", load_skills=[], description=\"Find shared utilities\", run_in_background=true, prompt=\"Cross-cutting concerns: FIND shared utilities across directories\")\n// ... more based on calculation\n```\n</dynamic-agents>\n\n### Main Session: Concurrent Analysis\n\n**While background agents run**, main session does:\n\n#### 1. Bash Structural Analysis\n```bash\n# Directory depth + file counts\nfind . -type d -not -path '*/\\.*' -not -path '*/node_modules/*' -not -path '*/venv/*' -not -path '*/dist/*' -not -path '*/build/*' | awk -F/ '{print NF-1}' | sort -n | uniq -c\n\n# Files per directory (top 30)\nfind . -type f -not -path '*/\\.*' -not -path '*/node_modules/*' | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn | head -30\n\n# Code concentration by extension\nfind . -type f \\( -name \"*.py\" -o -name \"*.ts\" -o -name \"*.tsx\" -o -name \"*.js\" -o -name \"*.go\" -o -name \"*.rs\" \\) -not -path '*/node_modules/*' | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn | head -20\n\n# Existing AGENTS.md / CLAUDE.md\nfind . -type f \\( -name \"AGENTS.md\" -o -name \"CLAUDE.md\" \\) -not -path '*/node_modules/*' 2>/dev/null\n```\n\n#### 2. Read Existing AGENTS.md\n```\nFor each existing file found:\n  Read(filePath=file)\n  Extract: key insights, conventions, anti-patterns\n  Store in EXISTING_AGENTS map\n```\n\nIf `--create-new`: Read all existing first (preserve context) \u2192 then delete all \u2192 regenerate.\n\n#### 3. LSP Codemap (if available)\n```\nLspServers()  # Check availability\n\n# Entry points (parallel)\nLspDocumentSymbols(filePath=\"src/index.ts\")\nLspDocumentSymbols(filePath=\"main.py\")\n\n# Key symbols (parallel)\nLspWorkspaceSymbols(filePath=\".\", query=\"class\")\nLspWorkspaceSymbols(filePath=\".\", query=\"interface\")\nLspWorkspaceSymbols(filePath=\".\", query=\"function\")\n\n# Centrality for top exports\nLspFindReferences(filePath=\"...\", line=X, character=Y)\n```\n\n**LSP Fallback**: If unavailable, rely on explore agents + AST-grep.\n\n### Collect Background Results\n\n```\n// After main session analysis done, collect all task results\nfor each task_id: background_output(task_id=\"...\")\n```\n\n**Merge: bash + LSP + existing + explore findings. Mark \"discovery\" as completed.**\n\n---\n\n## Phase 2: Scoring & Location Decision\n\n**Mark \"scoring\" as in_progress.**\n\n### Scoring Matrix\n\n| Factor | Weight | High Threshold | Source |\n|--------|--------|----------------|--------|\n| File count | 3x | >20 | bash |\n| Subdir count | 2x | >5 | bash |\n| Code ratio | 2x | >70% | bash |\n| Unique patterns | 1x | Has own config | explore |\n| Module boundary | 2x | Has index.ts/__init__.py | bash |\n| Symbol density | 2x | >30 symbols | LSP |\n| Export count | 2x | >10 exports | LSP |\n| Reference centrality | 3x | >20 refs | LSP |\n\n### Decision Rules\n\n| Score | Action |\n|-------|--------|\n| **Root (.)** | ALWAYS create |\n| **>15** | Create AGENTS.md |\n| **8-15** | Create if distinct domain |\n| **<8** | Skip (parent covers) |\n\n### Output\n```\nAGENTS_LOCATIONS = [\n  { path: \".\", type: \"root\" },\n  { path: \"src/hooks\", score: 18, reason: \"high complexity\" },\n  { path: \"src/api\", score: 12, reason: \"distinct domain\" }\n]\n```\n\n**Mark \"scoring\" as completed.**\n\n---\n\n## Phase 3: Generate AGENTS.md\n\n**Mark \"generate\" as in_progress.**\n\n<critical>\n**File Writing Rule**: If AGENTS.md already exists at the target path \u2192 use `Edit` tool. If it does NOT exist \u2192 use `Write` tool.\nNEVER use Write to overwrite an existing file. ALWAYS check existence first via `Read` or discovery results.\n</critical>\n\n### Root AGENTS.md (Full Treatment)\n\n```markdown\n# PROJECT KNOWLEDGE BASE\n\n**Generated:** {TIMESTAMP}\n**Commit:** {SHORT_SHA}\n**Branch:** {BRANCH}\n\n## OVERVIEW\n{1-2 sentences: what + core stack}\n\n## STRUCTURE\n\\`\\`\\`\n{root}/\n\u251C\u2500\u2500 {dir}/    # {non-obvious purpose only}\n\u2514\u2500\u2500 {entry}\n\\`\\`\\`\n\n## WHERE TO LOOK\n| Task | Location | Notes |\n|------|----------|-------|\n\n## CODE MAP\n{From LSP - skip if unavailable or project <10 files}\n\n| Symbol | Type | Location | Refs | Role |\n|--------|------|----------|------|------|\n\n## CONVENTIONS\n{ONLY deviations from standard}\n\n## ANTI-PATTERNS (THIS PROJECT)\n{Explicitly forbidden here}\n\n## UNIQUE STYLES\n{Project-specific}\n\n## COMMANDS\n\\`\\`\\`bash\n{dev/test/build}\n\\`\\`\\`\n\n## NOTES\n{Gotchas}\n```\n\n**Quality gates**: 50-150 lines, no generic advice, no obvious info.\n\n### Subdirectory AGENTS.md (Parallel)\n\nLaunch writing tasks for each location:\n\n```\nfor loc in AGENTS_LOCATIONS (except root):\n  task(category=\"transmission\", load_skills=[], run_in_background=false, description=\"Generate AGENTS.md\", prompt=\\`\n    Generate AGENTS.md for: ${loc.path}\n    - Reason: ${loc.reason}\n    - 30-80 lines max\n    - NEVER repeat parent content\n    - Sections: OVERVIEW (1 line), STRUCTURE (if >5 subdirs), WHERE TO LOOK, CONVENTIONS (if different), ANTI-PATTERNS\n  \\`)\n```\n\n**Wait for all. Mark \"generate\" as completed.**\n\n---\n\n## Phase 4: Review & Deduplicate\n\n**Mark \"review\" as in_progress.**\n\nFor each generated file:\n- Remove generic advice\n- Remove parent duplicates\n- Trim to size limits\n- Verify telegraphic style\n\n**Mark \"review\" as completed.**\n\n---\n\n## Final Report\n\n```\n=== init-deep Complete ===\n\nMode: {update | create-new}\n\nFiles:\n  [OK] ./AGENTS.md (root, {N} lines)\n  [OK] ./src/hooks/AGENTS.md ({N} lines)\n\nDirs Analyzed: {N}\nAGENTS.md Created: {N}\nAGENTS.md Updated: {N}\n\nHierarchy:\n  ./AGENTS.md\n  \u2514\u2500\u2500 src/hooks/AGENTS.md\n```\n\n---\n\n## Anti-Patterns\n\n- **Static agent count**: MUST vary agents based on project size/depth\n- **Sequential execution**: MUST parallel (explore + LSP concurrent)\n- **Ignoring existing**: ALWAYS read existing first, even with --create-new\n- **Over-documenting**: Not every dir needs AGENTS.md\n- **Redundancy**: Child never repeats parent\n- **Generic content**: Remove anything that applies to ALL projects\n- **Verbose style**: Telegraphic or die";

package/dist/features/builtin-commands/templates/redpill.d.ts

@@ -0,0 +1 @@
+export declare const REDPILL_TEMPLATE = "Toggle redpill mode for the current session.\n\nThis command will:\n1. Enable redpill mode \u2014 injects redpill mode instructions into every message\n2. Disable redpill mode \u2014 prevents redpill mode from activating (even on \"redpill\" keyword)\n3. Show current redpill mode status\n\nUsage:\n  /redpill enable \u2014 Force redpill mode on all messages\n  /redpill disable \u2014 Block redpill mode (keyword ignored)\n  /redpill status \u2014 Show current state\n\nThe change is per-session and clears when the session ends.\nBy default, redpill mode activates when the LLM or user mentions the \"redpill\" keyword.";

package/dist/features/builtin-commands/templates/research.d.ts

@@ -1 +1 @@
-export declare const RESEARCH_TEMPLATE = "# /research \u2014 Saturation Research Command\n\nExecute a systematic multi-round research process on the given topic.\n\n## Usage\n\n```\n/research <topic>                          \u2192 Full research (all directions)\n/research <topic> --scope=code            \u2192 Local codebase only\n/research <topic> --scope=docs            \u2192 Documentation only\n/research <topic> --scope=web             \u2192 Web search only\n/research <topic> --scope=oss             \u2192 OSS repos only\n/research <topic> --max-rounds=3          \u2192 Limit to 3 rounds\n```\n\n## What Happens\n\n1. Creates artifact directory: `.matrixx/research-<topic>-<timestamp>/`\n2. Spawns 4 parallel research agents (explore + operator swarms)\n3. Collects findings, identifies new leads\n4. Recursively follows leads until convergence (novelty-based stop, max 5 rounds)\n5. Verifies contested claims by running code\n6. Produces cited synthesis in `final-synthesis.md`\n\n## Output\n\nAll artifacts written to `.matrixx/research-<topic>-<timestamp>/`:\n- `round-N-findings.md` \u2014 per-round findings\n- `leads.md` \u2014 tracked leads\n- `contested-claims.md` \u2014 claims needing verification\n- `final-synthesis.md` \u2014 the final cited synthesis\n\n## Examples\n\n```\n/research how does context window management work in this codebase\n/research React 19 server component patterns --scope=web --max-rounds=3\n/research authentication middleware best practices --scope=all\n```\n\n---\n\nExecute the full research protocol using the ulw-research skill.";
+export declare const RESEARCH_TEMPLATE = "# /research \u2014 Saturation Research Command\n\nExecute a systematic multi-round research process on the given topic.\n\n## Usage\n\n```\n/research <topic>                          \u2192 Full research (all directions)\n/research <topic> --scope=code            \u2192 Local codebase only\n/research <topic> --scope=docs            \u2192 Documentation only\n/research <topic> --scope=web             \u2192 Web search only\n/research <topic> --scope=oss             \u2192 OSS repos only\n/research <topic> --max-rounds=3          \u2192 Limit to 3 rounds\n```\n\n## What Happens\n\n1. Creates artifact directory: `.matrixx/research-<topic>-<timestamp>/`\n2. Spawns 4 parallel research agents (explore + operator swarms)\n3. Collects findings, identifies new leads\n4. Recursively follows leads until convergence (novelty-based stop, max 5 rounds)\n5. Verifies contested claims by running code\n6. Produces cited synthesis in `final-synthesis.md`\n\n## Output\n\nAll artifacts written to `.matrixx/research-<topic>-<timestamp>/`:\n- `round-N-findings.md` \u2014 per-round findings\n- `leads.md` \u2014 tracked leads\n- `contested-claims.md` \u2014 claims needing verification\n- `final-synthesis.md` \u2014 the final cited synthesis\n\n## Examples\n\n```\n/research how does context window management work in this codebase\n/research React 19 server component patterns --scope=web --max-rounds=3\n/research authentication middleware best practices --scope=all\n```\n\n---\n\nExecute the full research protocol using the rp-research skill.";

package/dist/features/builtin-commands/types.d.ts

@@ -1,3 +1,3 @@
 import type { CommandDefinition } from "../command-loader";
-export type BuiltinCommandName = "init-deep" | "matrix-loop" | "cancel-loop" | "ulw-loop" | "refactor" | "start-work" | "stop-continuation" | "handoff" | "pickup" | "remove-deadcode" | "preset" | "end-ultrawork" | "research" | "assembly" | "ultrawork" | "bdd-pipeline" | "evolution" | "cleanup-tasks" | "task-list" | "plan-review" | "quality-audit" | "quality-assurance" | "humanize" | "security-audit";
+export type BuiltinCommandName = "init-deep" | "matrix-loop" | "cancel-loop" | "rp-loop" | "refactor" | "start-work" | "stop-continuation" | "handoff" | "pickup" | "remove-deadcode" | "preset" | "end-redpill" | "research" | "assembly" | "redpill" | "bdd-pipeline" | "evolution" | "cleanup-tasks" | "task-list" | "plan-review" | "quality-audit" | "quality-assurance" | "humanize" | "security-audit";
 export type BuiltinCommands = Record<string, CommandDefinition>;

package/dist/features/redpill-state/index.d.ts

@@ -0,0 +1 @@
+export { _resetRedpillStateForTesting, clearRedpillState, disableRedpill, enableRedpill, getRedpillState, } from "./manager";

package/dist/features/redpill-state/manager.d.ts

@@ -0,0 +1,6 @@
+export declare function getRedpillState(sessionID: string): "enabled" | "disabled" | undefined;
+export declare function enableRedpill(sessionID: string): void;
+export declare function disableRedpill(sessionID: string): void;
+export declare function clearRedpillState(sessionID: string): void;
+/** @internal */
+export declare function _resetRedpillStateForTesting(): void;

package/dist/features/session-memory/types.d.ts

@@ -32,9 +32,9 @@ export declare const MemoryEntryInputSchema: z.ZodObject<{
     pinned: z.ZodDefault<z.ZodBoolean>;
     text: z.ZodString;
     id: z.ZodString;
+    removed: z.ZodDefault<z.ZodBoolean>;
     sessionId: z.ZodString;
     messageId: z.ZodString;
-    removed: z.ZodDefault<z.ZodBoolean>;
     chars: z.ZodOptional<z.ZodNumber>;
     tokens: z.ZodOptional<z.ZodNumber>;
     createdAt: z.ZodOptional<z.ZodNumber>;

package/dist/features/task-storage/generation.d.ts

@@ -0,0 +1,13 @@
+import { type ReadErrorKind, TypedReadError } from "./read-errors";
+import { type Task } from "./types";
+export declare const STALE_GENERATION_KIND: ReadErrorKind;
+export declare class StaleGenerationError extends TypedReadError {
+    expected: number;
+    actual: number;
+    constructor(path: string, expected: number, actual: number);
+}
+export declare function currentTaskGeneration(task: Partial<Task> | null | undefined): number;
+export declare function assertCurrentGeneration(persistedGeneration: number, expectedGeneration: number, path: string): void;
+export declare function withBumpedGeneration(task: Task): Task;
+export declare function writeTaskFenced(filePath: string, task: Task, expectedGeneration: number): Task;
+export declare function readTaskGeneration(filePath: string): number;

package/dist/features/task-storage/index.d.ts

@@ -1,3 +1,4 @@
 /** task-storage barrel: explicit named re-exports of local modules only. */
-export { acquireLock, acquireLockWithRetry, generateTaskId, getProjectTaskDir, getTaskDir, listTaskFiles, migrateLegacyTasksIfNeeded, readJsonSafe, resolveTaskListId, sanitizePathSegment, writeJsonAtomic, } from "./storage";
+export { assertCurrentGeneration, currentTaskGeneration, readTaskGeneration, STALE_GENERATION_KIND, StaleGenerationError, withBumpedGeneration, writeTaskFenced, } from "./generation";
+export { acquireLock, acquireLockWithRetry, generateTaskId, getProjectTaskDir, getTaskDir, type LockHandle, type LockInfo, type LockResult, listTaskFiles, MAX_RETRIES, migrateLegacyTasksIfNeeded, RETRY_DELAY_MS, readJsonSafe, readJsonStrict, readLockFile, refreshLock, releaseLock, resolveTaskListId, StorageCorruptError, sanitizePathSegment, writeJsonAtomic, } from "./storage";
 export { type Task, TaskSchema, type TaskStatus, TaskStatusSchema, } from "./types";

package/dist/features/task-storage/read-errors.d.ts

@@ -0,0 +1,16 @@
+import type { z } from "zod";
+export type ReadErrorKind = "NotFound" | "Corrupt" | "Locked" | "TransientIO" | "StaleGeneration";
+export declare class TypedReadError extends Error {
+    kind: ReadErrorKind;
+    path: string;
+    byteSize: number;
+    constructor(kind: ReadErrorKind, path: string, byteSize: number, reason: string);
+}
+export type TypedReadResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: TypedReadError;
+};
+export declare function readJsonTyped<T>(filePath: string, schema: z.ZodType<T>): TypedReadResult<T>;

package/dist/features/task-storage/storage.d.ts

@@ -1,11 +1,21 @@
 import type { z } from "zod";
 import type { MatrixxConfig } from "../../config/schema";
+import { TypedReadError } from "./read-errors";
 export declare function getProjectTaskDir(directory: string): string;
 export declare function getTaskDir(config?: Partial<MatrixxConfig>, directory?: string): string;
 export declare function sanitizePathSegment(value: string): string;
 export declare function resolveTaskListId(config?: Partial<MatrixxConfig>): string;
+export declare class StorageCorruptError extends Error {
+    path: string;
+    byteSize: number;
+    reason: string;
+    constructor(path: string, byteSize: number, reason: string);
+}
 export declare function readJsonSafe<T>(filePath: string, schema: z.ZodType<T>): T | null;
+export declare function readJsonStrict<T>(filePath: string, schema: z.ZodType<T>): T;
 export declare function writeJsonAtomic(filePath: string, data: unknown): void;
+export declare const MAX_RETRIES = 4;
+export declare const RETRY_DELAY_MS = 15;
 export declare function acquireLockWithRetry(dirPath: string, retries?: number): Promise<{
     acquired: boolean;
     release: () => void;
@@ -17,7 +27,25 @@ export declare function migrateLegacyTasksIfNeeded(config: Partial<MatrixxConfig
     legacyDir: string;
     projectDir: string;
 };
-export declare function acquireLock(dirPath: string): {
+export interface LockInfo {
+    id: string;
+    ownerId: string;
+    pid: number;
+    generation: number;
+    timestamp: number;
+}
+export interface LockHandle {
     acquired: boolean;
+    ownerId?: string;
     release: () => void;
+}
+export type LockResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: TypedReadError;
 };
+export declare function readLockFile(dirPath: string): LockInfo | null;
+export declare function releaseLock(dirPath: string, ownerId: string): LockResult;
+export declare function refreshLock(dirPath: string, ownerId: string): LockResult;
+export declare function acquireLock(dirPath: string): LockHandle;

package/dist/features/task-storage/types.d.ts

@@ -25,5 +25,6 @@ export declare const TaskSchema: z.ZodObject<{
     parentID: z.ZodOptional<z.ZodString>;
     threadID: z.ZodOptional<z.ZodString>;
     projectRoot: z.ZodOptional<z.ZodString>;
+    generation: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strict>;
 export type Task = z.infer<typeof TaskSchema>;

package/dist/hooks/category-skill-reminder/formatter.d.ts

@@ -1,4 +1,4 @@
-import type { AvailableSkill } from "../../agents/dynamic-agent-prompt-builder";
+import type { AvailableSkill } from "../../agents/shared/dynamic-agent-prompt-builder";
 export declare function buildReminderMessage(availableSkills: AvailableSkill[]): string;
 export interface NudgeMessageEvent {
     skill: string;

package/dist/hooks/category-skill-reminder/hook.d.ts

@@ -1,4 +1,4 @@
-import type { AvailableSkill } from "../../agents/dynamic-agent-prompt-builder";
+import type { AvailableSkill } from "../../agents/shared/dynamic-agent-prompt-builder";
 import type { MatrixxContext } from "../../plugin/tool/context";
 export type { NudgeEvent, NudgeInput } from "./detector";
 export { detectNudge } from "./detector";

package/dist/hooks/keyword-detector/constants.d.ts

@@ -1,8 +1,8 @@
 export { CODE_BLOCK_PATTERN, INLINE_CODE_PATTERN } from "../../shared/policy/code-patterns";
 export { ANALYZE_MESSAGE, ANALYZE_PATTERN } from "./analyze/default";
 export { DOCS_MESSAGE, DOCS_PATTERN } from "./docs/default";
+export { getRedpillMessage, isPlannerAgent } from "./redpill";
 export { SEARCH_MESSAGE, SEARCH_PATTERN } from "./search/default";
-export { getUltraworkMessage, isPlannerAgent } from "./ultrawork";
 type KeywordDetector = {
     pattern: RegExp;
     message: string | ((agentName?: string, modelID?: string) => string);

package/dist/hooks/keyword-detector/detector.d.ts

@@ -1,5 +1,5 @@
 interface DetectedKeyword {
-    type: "ultrawork" | "search" | "analyze" | "docs";
+    type: "redpill" | "search" | "analyze" | "docs";
     message: string;
 }
 export declare function removeCodeBlocks(text: string): string;