maskweaver 0.9.4 → 0.9.6

package/dist/shared-context/watchdog.d.ts

@@ -1,144 +1,17 @@
-/**
- * Watchdog - Squad Timeout Monitoring
- *
- * Monitors squad health and detects stuck or unresponsive agents.
- * "If you can't measure it, you can't improve it." - Brendan Gregg
- *
- * Key metrics:
- * - Elapsed time since last activity (updatedAt)
- * - Time remaining before timeout threshold
- * - Grace period for cleanup before hard kill
- *
- * Design principles:
- * - Pure functions for timeout checking (no side effects)
- * - Deterministic behavior for testing
- * - Observability-first: expose all timing details
- *
- * @author Kent Beck's Dummy Human
- */
 import type { SquadState, TaskState, TimeoutStatus } from "./types.js";
 import type { Session } from "./session.js";
-/**
- * Check if a squad has exceeded its timeout threshold.
- * Pure function based on squadState.updatedAt timestamp.
- *
- * This is the primary health check for detecting stuck agents.
- * A squad is considered stuck if no activity has occurred within
- * the timeout period (default: 5 minutes).
- *
- * @param squadState - Current squad state with updatedAt timestamp
- * @param timeoutMs - Optional custom timeout (defaults to LIMITS.watchdogTimeoutMs)
- * @returns TimeoutStatus with expiration state and timing details
- *
- * @example
- * const status = checkSquadTimeout(squadState);
- * if (status.isExpired) {
- *   console.log(`Squad stuck for ${status.elapsedMs}ms`);
- *   await markSquadExpired(session, squadState.squadId);
- * }
- *
- * @example
- * // With custom timeout for long-running tasks
- * const status = checkSquadTimeout(squadState, 30 * 60 * 1000); // 30 minutes
- */
 export declare function checkSquadTimeout(squadState: SquadState, timeoutMs?: number): TimeoutStatus;
-/**
- * Check if a task has exceeded its timeout threshold.
- * Pure function - deterministic and side-effect free.
- *
- * "If you can't measure it, you can't improve it." - Brendan Gregg
- *
- * This enables fine-grained observability at the task level,
- * complementing squad-level timeout checks.
- *
- * @param task - TaskState with optional startedAt timestamp
- * @param timeoutMs - Timeout threshold (defaults to LIMITS.watchdogTimeoutMs)
- * @returns TimeoutStatus or null if task hasn't started
- *
- * @example
- * const status = checkTaskTimeout(task);
- * if (status === null) {
- *   console.log("Task hasn't started yet");
- * } else if (status.isExpired) {
- *   console.log(`Task stuck for ${status.elapsedMs}ms`);
- * }
- *
- * @example
- * // With custom timeout for quick tasks
- * const status = checkTaskTimeout(task, 60 * 1000); // 1 minute
- */
 export declare function checkTaskTimeout(task: TaskState, timeoutMs?: number): TimeoutStatus | null;
-/**
- * Mark a squad as expired due to timeout.
- * Sets status to "failed" and logs the timeout event.
- *
- * This should be called after checkSquadTimeout() returns isExpired: true.
- * The function is idempotent - calling it multiple times is safe.
- *
- * @param session - Parent session containing the squad
- * @param squadId - ID of the squad to expire
- * @returns Updated squad state with status="failed"
- *
- * @example
- * const status = checkSquadTimeout(squadState);
- * if (status.isExpired) {
- *   const failedState = await markSquadExpired(session, squadId);
- *   console.log(`Squad ${squadId} expired after ${status.elapsedMs}ms`);
- * }
- */
 export declare function markSquadExpired(session: Session, squadId: string): Promise<SquadState>;
-/**
- * Summary of a watchdog run.
- * "If you can't measure it, you can't improve it." - Brendan Gregg
- */
 export interface WatchdogSummary {
-    /** Number of squads checked */
     checkedSquads: number;
-    /** Number of tasks checked (across all squads) */
     checkedTasks: number;
-    /** IDs of squads that were found expired */
     expiredSquads: string[];
-    /** Tasks that were found expired */
     expiredTasks: Array<{
         squadId: string;
         taskId: string;
     }>;
 }
-/**
- * Run watchdog check on all active squads and tasks.
- * Marks expired squads/tasks as failed.
- *
- * This is meant to be called periodically (e.g., every 30 seconds)
- * to detect and handle stuck agents.
- *
- * "If you can't measure it, you can't improve it." - Brendan Gregg
- *
- * The dryRun mode allows "measure before fix" - check without modifying state.
- *
- * @param session - Session to check
- * @param options - Optional configuration
- * @returns Summary of watchdog run with all metrics
- *
- * @example
- * // Periodic watchdog check (production mode)
- * const summary = await runWatchdog(session);
- * console.log(`Checked ${summary.checkedSquads} squads`);
- * console.log(`Expired: ${summary.expiredSquads.length} squads`);
- *
- * @example
- * // Dry run for monitoring without side effects
- * const summary = await runWatchdog(session, { dryRun: true });
- * if (summary.expiredSquads.length > 0) {
- *   alertOnCall(summary);
- * }
- *
- * @example
- * // Custom timeouts for specific workloads
- * const summary = await runWatchdog(session, {
- *   squadTimeoutMs: 30 * 60 * 1000, // 30 minutes
- *   taskTimeoutMs: 10 * 60 * 1000,  // 10 minutes
- * });
- */
 export declare function runWatchdog(session: Session, options?: {
     squadTimeoutMs?: number;
     taskTimeoutMs?: number;

package/dist/shared-context/watchdog.js

@@ -1,37 +1,7 @@
-/**
- * Watchdog - Squad Timeout Monitoring
- *
- * Monitors squad health and detects stuck or unresponsive agents.
- * "If you can't measure it, you can't improve it." - Brendan Gregg
- *
- * Key metrics:
- * - Elapsed time since last activity (updatedAt)
- * - Time remaining before timeout threshold
- * - Grace period for cleanup before hard kill
- *
- * Design principles:
- * - Pure functions for timeout checking (no side effects)
- * - Deterministic behavior for testing
- * - Observability-first: expose all timing details
- *
- * @author Kent Beck's Dummy Human
- */
 import { LIMITS } from "./types.js";
 import { getSquad, updateSquadState } from "./squad.js";
 import { updateTask } from "./task.js";
 import { logEvent } from "./logger.js";
-// ============================================================================
-// Internal Helpers
-// ============================================================================
-/**
- * Calculate timeout status from last activity timestamp.
- * Pure function - deterministic and side-effect free.
- *
- * @param lastActivityAt - ISO timestamp of last recorded activity
- * @param timeoutMs - Timeout threshold in milliseconds
- * @param now - Current time (injectable for testing)
- * @returns Computed timeout status with all timing details
- */
 function getTimeoutStatus(lastActivityAt, timeoutMs, now = new Date()) {
     const lastActivity = new Date(lastActivityAt);
     const elapsedMs = now.getTime() - lastActivity.getTime();
@@ -44,140 +14,27 @@ function getTimeoutStatus(lastActivityAt, timeoutMs, now = new Date()) {
         lastActivityAt,
     };
 }
-// ============================================================================
-// Timeout Checking - Pure Functions
-// ============================================================================
-/**
- * Check if a squad has exceeded its timeout threshold.
- * Pure function based on squadState.updatedAt timestamp.
- *
- * This is the primary health check for detecting stuck agents.
- * A squad is considered stuck if no activity has occurred within
- * the timeout period (default: 5 minutes).
- *
- * @param squadState - Current squad state with updatedAt timestamp
- * @param timeoutMs - Optional custom timeout (defaults to LIMITS.watchdogTimeoutMs)
- * @returns TimeoutStatus with expiration state and timing details
- *
- * @example
- * const status = checkSquadTimeout(squadState);
- * if (status.isExpired) {
- *   console.log(`Squad stuck for ${status.elapsedMs}ms`);
- *   await markSquadExpired(session, squadState.squadId);
- * }
- *
- * @example
- * // With custom timeout for long-running tasks
- * const status = checkSquadTimeout(squadState, 30 * 60 * 1000); // 30 minutes
- */
 export function checkSquadTimeout(squadState, timeoutMs) {
     const effectiveTimeout = timeoutMs ?? LIMITS.watchdogTimeoutMs;
     return getTimeoutStatus(squadState.updatedAt, effectiveTimeout);
 }
-// ============================================================================
-// Task Timeout Checking - Fine-grained observability
-// ============================================================================
-/**
- * Check if a task has exceeded its timeout threshold.
- * Pure function - deterministic and side-effect free.
- *
- * "If you can't measure it, you can't improve it." - Brendan Gregg
- *
- * This enables fine-grained observability at the task level,
- * complementing squad-level timeout checks.
- *
- * @param task - TaskState with optional startedAt timestamp
- * @param timeoutMs - Timeout threshold (defaults to LIMITS.watchdogTimeoutMs)
- * @returns TimeoutStatus or null if task hasn't started
- *
- * @example
- * const status = checkTaskTimeout(task);
- * if (status === null) {
- *   console.log("Task hasn't started yet");
- * } else if (status.isExpired) {
- *   console.log(`Task stuck for ${status.elapsedMs}ms`);
- * }
- *
- * @example
- * // With custom timeout for quick tasks
- * const status = checkTaskTimeout(task, 60 * 1000); // 1 minute
- */
 export function checkTaskTimeout(task, timeoutMs) {
-    // Task hasn't started - no timeout to check
     if (!task.startedAt) {
         return null;
     }
     const effectiveTimeout = timeoutMs ?? LIMITS.watchdogTimeoutMs;
     return getTimeoutStatus(task.startedAt, effectiveTimeout);
 }
-// ============================================================================
-// State Mutations - Expire Stuck Squads
-// ============================================================================
-/**
- * Mark a squad as expired due to timeout.
- * Sets status to "failed" and logs the timeout event.
- *
- * This should be called after checkSquadTimeout() returns isExpired: true.
- * The function is idempotent - calling it multiple times is safe.
- *
- * @param session - Parent session containing the squad
- * @param squadId - ID of the squad to expire
- * @returns Updated squad state with status="failed"
- *
- * @example
- * const status = checkSquadTimeout(squadState);
- * if (status.isExpired) {
- *   const failedState = await markSquadExpired(session, squadId);
- *   console.log(`Squad ${squadId} expired after ${status.elapsedMs}ms`);
- * }
- */
 export async function markSquadExpired(session, squadId) {
-    // Log the timeout event for observability
     await logEvent(session, squadId, {
         type: "error",
         message: "Squad timeout expired",
     });
-    // Update state to failed
     const updatedState = await updateSquadState(session, squadId, {
         status: "failed",
     });
     return updatedState;
 }
-/**
- * Run watchdog check on all active squads and tasks.
- * Marks expired squads/tasks as failed.
- *
- * This is meant to be called periodically (e.g., every 30 seconds)
- * to detect and handle stuck agents.
- *
- * "If you can't measure it, you can't improve it." - Brendan Gregg
- *
- * The dryRun mode allows "measure before fix" - check without modifying state.
- *
- * @param session - Session to check
- * @param options - Optional configuration
- * @returns Summary of watchdog run with all metrics
- *
- * @example
- * // Periodic watchdog check (production mode)
- * const summary = await runWatchdog(session);
- * console.log(`Checked ${summary.checkedSquads} squads`);
- * console.log(`Expired: ${summary.expiredSquads.length} squads`);
- *
- * @example
- * // Dry run for monitoring without side effects
- * const summary = await runWatchdog(session, { dryRun: true });
- * if (summary.expiredSquads.length > 0) {
- *   alertOnCall(summary);
- * }
- *
- * @example
- * // Custom timeouts for specific workloads
- * const summary = await runWatchdog(session, {
- *   squadTimeoutMs: 30 * 60 * 1000, // 30 minutes
- *   taskTimeoutMs: 10 * 60 * 1000,  // 10 minutes
- * });
- */
 export async function runWatchdog(session, options) {
     const squadTimeoutMs = options?.squadTimeoutMs ?? LIMITS.watchdogTimeoutMs;
     const taskTimeoutMs = options?.taskTimeoutMs ?? LIMITS.watchdogTimeoutMs;
@@ -186,15 +43,12 @@ export async function runWatchdog(session, options) {
     const expiredTasks = [];
     let checkedSquads = 0;
     let checkedTasks = 0;
-    // Iterate through all squads in the session
     for (const squadId of session.manifest.squads) {
         const squad = await getSquad(session, squadId);
-        // Skip if squad doesn't exist (may have been cleaned up)
         if (!squad) {
             continue;
         }
         checkedSquads++;
-        // Only check active squads (skip completed/failed)
         if (squad.state.status === "active" || squad.state.status === "pending") {
             const squadStatus = checkSquadTimeout(squad.state, squadTimeoutMs);
             if (squadStatus.isExpired) {
@@ -204,9 +58,7 @@ export async function runWatchdog(session, options) {
                 }
             }
         }
-        // Check all active tasks in this squad
         for (const task of squad.state.tasks) {
-            // Only check tasks that are in progress (active status with startedAt)
             if (task.status === "active" && task.startedAt) {
                 checkedTasks++;
                 const taskStatus = checkTaskTimeout(task, taskTimeoutMs);

package/dist/shared-context/worktree.d.ts

@@ -1,11 +1,3 @@
-/**
- * Git Worktree Manager
- *
- * Provides isolated working directories for parallel task execution.
- * Each task gets its own git worktree to prevent file conflicts.
- *
- * @author Linus Torvalds' Dummy Human
- */
 export interface WorktreeInfo {
     path: string;
     branch: string;
@@ -13,75 +5,15 @@ export interface WorktreeInfo {
     createdAt: string;
 }
 export interface WorktreeManagerOptions {
-    /** Root git repository path */
     repoRoot: string;
-    /** Base directory for worktrees (default: <repoRoot>/.worktrees) */
     worktreeBase?: string;
-    /** Branch prefix for worktree branches (default: "squad/") */
     branchPrefix?: string;
 }
 export interface WorktreeManager {
-    /**
-     * Create isolated worktree for a task.
-     * @param taskId - The ID of the task to associate with the worktree.
-     * @param baseBranch - The branch to create the worktree from (defaults to current branch).
-     * @returns Information about the created worktree.
-     * @throws {Error} If git command fails.
-     * @example
-     * const manager = createWorktreeManager({ repoRoot: '/path/to/repo' });
-     * const info = await manager.create('task-123');
-     * console.log(info.path); // /path/to/repo/.worktrees/task-123
-     */
     create(taskId: string, baseBranch?: string): Promise<WorktreeInfo>;
-    /**
-     * Remove worktree after task completion.
-     * @param taskId - The ID of the task whose worktree should be removed.
-     * @throws {Error} If git command fails.
-     * @example
-     * const manager = createWorktreeManager({ repoRoot: '/path/to/repo' });
-     * await manager.remove('task-123');
-     */
     remove(taskId: string): Promise<void>;
-    /**
-     * List all active worktrees managed by this manager.
-     * @returns A list of active worktree information.
-     * @throws {Error} If git command fails.
-     * @example
-     * const manager = createWorktreeManager({ repoRoot: '/path/to/repo' });
-     * const worktrees = await manager.list();
-     * console.log(worktrees);
-     */
     list(): Promise<WorktreeInfo[]>;
-    /**
-     * Clean up all worktrees managed by this manager (for session end).
-     * @throws {Error} If git command fails.
-     * @example
-     * const manager = createWorktreeManager({ repoRoot: '/path/to/repo' });
-     * await manager.cleanup();
-     */
     cleanup(): Promise<void>;
-    /**
-     * Get worktree info for a specific task.
-     * @param taskId - The ID of the task.
-     * @returns WorktreeInfo if found, otherwise null.
-     * @throws {Error} If git command fails.
-     * @example
-     * const manager = createWorktreeManager({ repoRoot: '/path/to/repo' });
-     * const info = await manager.get('task-123');
-     * if (info) console.log(info.branch);
-     */
     get(taskId: string): Promise<WorktreeInfo | null>;
 }
-/**
- * Create a WorktreeManager instance.
- * Uses git worktree add/remove commands internally.
- * @param options - Configuration options for the WorktreeManager.
- * @returns A WorktreeManager instance.
- * @example
- * const manager = createWorktreeManager({
- *   repoRoot: process.cwd(),
- *   worktreeBase: './.squad-worktrees',
- *   branchPrefix: 'squad-task/'
- * });
- */
 export declare function createWorktreeManager(options: WorktreeManagerOptions): WorktreeManager;

package/dist/shared-context/worktree.js

@@ -1,28 +1,8 @@
-/**
- * Git Worktree Manager
- *
- * Provides isolated working directories for parallel task execution.
- * Each task gets its own git worktree to prevent file conflicts.
- *
- * @author Linus Torvalds' Dummy Human
- */
 import { execFile } from 'child_process';
 import { join, resolve } from 'path';
 import { promisify } from 'util';
 import { mkdir } from 'fs/promises';
 const execFileAsync = promisify(execFile);
-/**
- * Create a WorktreeManager instance.
- * Uses git worktree add/remove commands internally.
- * @param options - Configuration options for the WorktreeManager.
- * @returns A WorktreeManager instance.
- * @example
- * const manager = createWorktreeManager({
- *   repoRoot: process.cwd(),
- *   worktreeBase: './.squad-worktrees',
- *   branchPrefix: 'squad-task/'
- * });
- */
 export function createWorktreeManager(options) {
     const repoRoot = resolve(options.repoRoot);
     const worktreeBase = resolve(repoRoot, options.worktreeBase || '.worktrees');
@@ -43,9 +23,7 @@ export function createWorktreeManager(options) {
         async create(taskId, baseBranch) {
             const worktreePath = getWorktreePath(taskId);
             const branchName = getBranchName(taskId);
-            // Ensure worktreeBase directory exists
             await mkdir(worktreeBase, { recursive: true });
-            // Check if worktree already exists
             try {
                 const existing = await this.get(taskId);
                 if (existing) {
@@ -53,11 +31,8 @@ export function createWorktreeManager(options) {
                 }
             }
             catch {
-                // Ignore error if list fails, proceed to create
             }
-            // Determine the base commit to branch from
             const base = baseBranch || 'HEAD';
-            // Create worktree with a new branch in one step
             await git(['worktree', 'add', '-b', branchName, worktreePath, base]);
             return {
                 path: worktreePath,
@@ -69,15 +44,12 @@ export function createWorktreeManager(options) {
         async remove(taskId) {
             const worktreePath = getWorktreePath(taskId);
             const branchName = getBranchName(taskId);
-            // Check if worktree exists before trying to remove
             const existing = await this.get(taskId);
             if (!existing) {
                 console.warn(`Worktree for task ${taskId} not found at ${worktreePath}. Skipping removal.`);
                 return;
             }
-            // Remove worktree
             await git(['worktree', 'remove', worktreePath]);
-            // Remove associated branch
             try {
                 await git(['branch', '-D', branchName]);
             }
@@ -93,7 +65,6 @@ export function createWorktreeManager(options) {
             for (const line of lines) {
                 if (line.startsWith('worktree ')) {
                     if (currentWorktree.path) {
-                        // Check if it's a squad worktree
                         if (currentWorktree.branch && currentWorktree.branch.startsWith(branchPrefix)) {
                             const taskId = currentWorktree.branch.substring(branchPrefix.length);
                             if (taskId) {
@@ -101,7 +72,7 @@ export function createWorktreeManager(options) {
                                     path: currentWorktree.path,
                                     branch: currentWorktree.branch,
                                     taskId: taskId,
-                                    createdAt: new Date().toISOString(), // Placeholder, git worktree list doesn't provide creation time
+                                    createdAt: new Date().toISOString(),
                                 });
                             }
                         }
@@ -109,13 +80,10 @@ export function createWorktreeManager(options) {
                     currentWorktree = { path: line.substring('worktree '.length) };
                 }
                 else if (line.startsWith('branch ')) {
-                    // git outputs full ref, e.g. "refs/heads/squad/task-123"
                     const ref = line.substring('branch '.length).trim();
                     currentWorktree.branch = ref.replace(/^refs\/heads\//, '');
                 }
-                // Other fields like HEAD, bare, etc., are ignored for WorktreeInfo
             }
-            // Add the last parsed worktree if it's a squad worktree
             if (currentWorktree.path && currentWorktree.branch && currentWorktree.branch.startsWith(branchPrefix)) {
                 const taskId = currentWorktree.branch.substring(branchPrefix.length);
                 if (taskId) {
@@ -132,7 +100,7 @@ export function createWorktreeManager(options) {
         async cleanup() {
             const worktrees = await this.list();
             for (const worktree of worktrees) {
-                if (worktree.branch.startsWith(branchPrefix)) { // Only clean up squad-managed worktrees
+                if (worktree.branch.startsWith(branchPrefix)) {
                     await this.remove(worktree.taskId);
                 }
             }

package/dist/verify/budget.d.ts

@@ -1,44 +1,15 @@
-/**
- * Budget Tracker
- *
- * Tracks verification costs and enforces budget limits
- */
 import type { BudgetState, ReviewerTier, VerifyConfig } from "./types.js";
-/**
- * Budget tracker class
- */
 export declare class BudgetTracker {
     private readonly sessionLimit;
     private readonly checkLimit;
     private sessionTotal;
     private checkTotal;
     constructor(sessionLimit: number, checkLimit: number);
-    /**
-     * Estimate cost for a verification request
-     */
     estimateCost(content: string, context: string | undefined, reviewer: ReviewerTier): number;
-    /**
-     * Check if a verification can proceed within budget
-     */
     canProceed(estimatedCost: number): boolean;
-    /**
-     * Record actual cost
-     */
     recordCost(cost: number): void;
-    /**
-     * Get current budget state
-     */
     getState(): BudgetState;
-    /**
-     * Reset session budget
-     */
     resetSession(): void;
-    /**
-     * Reset check budget
-     */
     resetCheck(): void;
 }
-/**
- * Create budget tracker from config
- */
 export declare function createBudgetTracker(config: VerifyConfig): BudgetTracker;

package/dist/verify/budget.js

@@ -1,19 +1,7 @@
-/**
- * Budget Tracker
- *
- * Tracks verification costs and enforces budget limits
- */
 import { COST_RATES } from "./types.js";
-/**
- * Estimates token count from text length
- * Rough approximation: 1 token ≈ 4 characters
- */
 function estimateTokens(text) {
     return Math.ceil(text.length / 4);
 }
-/**
- * Budget tracker class
- */
 export class BudgetTracker {
     sessionLimit;
     checkLimit;
@@ -23,21 +11,14 @@ export class BudgetTracker {
         this.sessionLimit = sessionLimit;
         this.checkLimit = checkLimit;
     }
-    /**
-     * Estimate cost for a verification request
-     */
     estimateCost(content, context, reviewer) {
         const contentTokens = estimateTokens(content);
         const contextTokens = context ? estimateTokens(context) : 0;
         const totalTokens = contentTokens + contextTokens;
-        // Add overhead for prompt template and response (~500 tokens)
         const totalWithOverhead = totalTokens + 500;
         const costPer1K = COST_RATES[reviewer];
         return (totalWithOverhead / 1000) * costPer1K;
     }
-    /**
-     * Check if a verification can proceed within budget
-     */
     canProceed(estimatedCost) {
         if (this.sessionTotal + estimatedCost > this.sessionLimit) {
             return false;
@@ -47,16 +28,10 @@ export class BudgetTracker {
         }
         return true;
     }
-    /**
-     * Record actual cost
-     */
     recordCost(cost) {
         this.sessionTotal += cost;
         this.checkTotal = cost;
     }
-    /**
-     * Get current budget state
-     */
     getState() {
         return {
             sessionTotal: this.sessionTotal,
@@ -66,23 +41,14 @@ export class BudgetTracker {
             exceeded: this.sessionTotal >= this.sessionLimit,
         };
     }
-    /**
-     * Reset session budget
-     */
     resetSession() {
         this.sessionTotal = 0;
         this.checkTotal = 0;
     }
-    /**
-     * Reset check budget
-     */
     resetCheck() {
         this.checkTotal = 0;
     }
 }
-/**
- * Create budget tracker from config
- */
 export function createBudgetTracker(config) {
     return new BudgetTracker(config.budget.maxPerSessionUSD, config.budget.maxPerCheckUSD);
 }

package/dist/verify/critical-files.d.ts

@@ -1,21 +1,4 @@
-/**
- * Critical File Detection
- *
- * Identifies files that require extra scrutiny
- */
-/**
- * Default critical file patterns
- */
 export declare const DEFAULT_CRITICAL_PATTERNS: string[];
-/**
- * Check if a file path matches critical file patterns
- */
 export declare function isCriticalFile(filePath: string, patterns?: string[]): boolean;
-/**
- * Get matched critical patterns for a file
- */
 export declare function getMatchedPatterns(filePath: string, patterns?: string[]): string[];
-/**
- * Categorize criticality level
- */
 export declare function getCriticalityLevel(filePath: string): "critical" | "sensitive" | "normal";