opencode-pilot 0.6.0 → 0.7.0

package/README.md

@@ -75,6 +75,11 @@ Create prompt templates as markdown files in `~/.config/opencode-pilot/templates
 opencode-pilot start              # Start the service (foreground)
 opencode-pilot status             # Check status
 opencode-pilot config             # Validate and show config
+opencode-pilot clear              # Show state summary
+opencode-pilot clear --all        # Clear all processed state
+opencode-pilot clear --expired    # Clear expired entries (uses configured TTL)
+opencode-pilot clear --source X   # Clear entries for source X
+opencode-pilot clear --item ID    # Clear specific item
 opencode-pilot test-source NAME   # Test a source
 opencode-pilot test-mapping MCP   # Test field mappings
 ```
@@ -86,6 +91,22 @@ opencode-pilot test-mapping MCP   # Test field mappings
 3. **Spawn sessions** - Start `opencode run` with the appropriate prompt template
 4. **Track state** - Remember which items have been processed
 
+## Known Issues
+
+### Working directory doesn't switch when templates create worktrees/devcontainers
+
+When a template instructs the agent to create a git worktree or switch to a devcontainer, OpenCode's internal working directory context (`Instance.directory`) doesn't update. This means:
+
+- The "Session changes" panel shows diffs from the original directory
+- File tools may resolve paths relative to the wrong location
+- The agent works in the new directory, but OpenCode doesn't follow
+
+**Workaround**: Start OpenCode directly in the target directory, or use separate terminal sessions.
+
+**Upstream issue**: [anomalyco/opencode#6697](https://github.com/anomalyco/opencode/issues/6697)
+
+**Related**: [opencode-devcontainers#103](https://github.com/athal7/opencode-devcontainers/issues/103)
+
 ## Related
 
 - [opencode-devcontainers](https://github.com/athal7/opencode-devcontainers) - Run multiple devcontainer instances for OpenCode

package/bin/opencode-pilot

@@ -116,10 +116,17 @@ Commands:
   start                Start the polling service (foreground)
   status               Show service status
   config               Validate and show configuration
+  clear                Clear processed state entries
   test-source NAME     Test a source by fetching items and showing mappings
   test-mapping MCP     Test field mappings with sample JSON input
   help                 Show this help message
 
+Clear options:
+  --all                Clear all processed entries
+  --source NAME        Clear entries for a specific source
+  --item ID            Clear a specific item
+  --expired            Clear only expired entries (uses configured TTL)
+
 The service handles:
 - Polling for GitHub/Linear issues to work on
 - Spawning OpenCode sessions for ready items
@@ -128,6 +135,8 @@ Examples:
   opencode-pilot start                   # Start service (foreground)
   opencode-pilot status                  # Check status
   opencode-pilot config                  # Validate and show config
+  opencode-pilot clear --all             # Clear all processed state
+  opencode-pilot clear --expired         # Clear expired entries
   opencode-pilot test-source my-issues   # Test a source
   echo '{"url":"https://linear.app/team/issue/PROJ-123/title"}' | opencode-pilot test-mapping linear
 `);
@@ -602,6 +611,59 @@ async function testMappingCommand(mcpName) {
   }
 }
 
+// ============================================================================
+// Clear Command
+// ============================================================================
+
+async function clearCommand(flags) {
+  try {
+    const { createPoller } = await import(join(serviceDir, "poller.js"));
+    const { loadRepoConfig, getCleanupTtlDays } = await import(join(serviceDir, "repo-config.js"));
+    
+    // Load config for TTL settings
+    if (existsSync(PILOT_CONFIG_FILE)) {
+      loadRepoConfig(PILOT_CONFIG_FILE);
+    }
+    
+    const poller = createPoller();
+    const beforeCount = poller.getProcessedCount();
+    
+    if (flags.all) {
+      poller.clearState();
+      console.log(`Cleared all ${beforeCount} processed entries`);
+    } else if (flags.source) {
+      const removed = poller.clearBySource(flags.source);
+      console.log(`Cleared ${removed} entries for source: ${flags.source}`);
+    } else if (flags.item) {
+      if (poller.isProcessed(flags.item)) {
+        poller.clearProcessed(flags.item);
+        console.log(`Cleared item: ${flags.item}`);
+      } else {
+        console.log(`Item not found in processed state: ${flags.item}`);
+      }
+    } else if (flags.expired) {
+      const ttlDays = getCleanupTtlDays();
+      const removed = poller.cleanupExpired(ttlDays);
+      console.log(`Cleared ${removed} entries older than ${ttlDays} days`);
+    } else {
+      // No flags - show current state summary
+      console.log("Poll state summary:");
+      console.log(`  Total entries: ${beforeCount}`);
+      console.log(`  State file: ~/.config/opencode-pilot/poll-state.json`);
+      console.log("");
+      console.log("Usage:");
+      console.log("  opencode-pilot clear --all           Clear all entries");
+      console.log("  opencode-pilot clear --source NAME   Clear entries for source");
+      console.log("  opencode-pilot clear --item ID       Clear specific item");
+      console.log("  opencode-pilot clear --expired       Clear expired entries");
+    }
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    console.error("The state file may be corrupted. Try: opencode-pilot clear --all");
+    process.exit(1);
+  }
+}
+
 // ============================================================================
 // Main
 // ============================================================================
@@ -628,6 +690,10 @@ async function main() {
       await configCommand();
       break;
 
+    case "clear":
+      await clearCommand(parseArgs(args).flags);
+      break;
+
     case "test-source":
       await testSourceCommand(subcommand);
       break;

package/examples/config.yaml

@@ -1,61 +1,38 @@
 # Example config.yaml for opencode-pilot
-#
-# Copy to ~/.config/opencode-pilot/config.yaml and customize
-# Also create templates/ directory with prompt template files
+# Copy to ~/.config/opencode-pilot/config.yaml
 
-# =============================================================================
-# DEFAULTS - Applied to all sources (source values override these)
-# =============================================================================
 defaults:
-  agent: plan                        # Default agent for all sources
-  prompt: default                    # Default prompt template
+  agent: plan
+  prompt: default
 
-# =============================================================================
-# SOURCES - What to poll
-#
-# Three syntax options:
-#   1. Presets: Use built-in presets for common patterns
-#   2. Shorthand: Use `github: "query"` for GitHub sources
-#   3. Full: Specify tool, args, item for custom sources
-# =============================================================================
 sources:
-  # ----- PRESET SYNTAX (recommended for common patterns) -----
-  
-  # GitHub issues assigned to me
+  # Presets - common patterns with sensible defaults
   - preset: github/my-issues
     prompt: worktree
 
-  # GitHub PRs needing my review
   - preset: github/review-requests
     prompt: review
 
-  # My PRs that have change requests (filter to specific repos)
   - preset: github/my-prs-feedback
     prompt: review-feedback
-    repos:                           # Optional: filter to specific repos
+    repos:
       - myorg/backend
       - myorg/frontend
 
-  # Linear issues (requires teamId and assigneeId)
-  # Find IDs via: opencode-pilot discover linear
+  # Linear (requires teamId and assigneeId)
   - preset: linear/my-issues
     args:
-      teamId: "your-team-uuid"      # Replace with actual team UUID
-      assigneeId: "your-user-uuid"  # Replace with actual user UUID
+      teamId: "your-team-uuid"
+      assigneeId: "your-user-uuid"
       status: "In Progress"
     working_dir: ~/code/myproject
     prompt: worktree
 
-  # ----- SHORTHAND SYNTAX (for custom GitHub queries) -----
-  
-  # Custom GitHub query with shorthand
+  # GitHub shorthand syntax
   # - name: urgent-issues
   #   github: "is:issue assignee:@me label:urgent state:open"
-  #   prompt: worktree
 
-  # ----- FULL SYNTAX (for non-GitHub sources or full control) -----
-  
-  # Apple Reminders example (requires tools config below)
+  # Full syntax for custom MCP sources (e.g., Apple Reminders)
   # - name: agent-tasks
   #   tool:
   #     mcp: apple-reminders
@@ -65,19 +42,8 @@ sources:
   #     completed: false
   #   item:
   #     id: "reminder:{id}"
-  #   prompt: agent-planning
-  #   working_dir: ~
 
-# =============================================================================
-# TOOLS - Field mappings for custom MCP servers (OPTIONAL)
-#
-# Note: GitHub and Linear presets include built-in mappings.
-# Only needed for custom sources or to override preset defaults.
-#
-# Each tool provider can specify:
-#   response_key: Key to extract array from response (e.g., "reminders")
-#   mappings: Field name translations (e.g., { body: "notes" })
-# =============================================================================
+# Tool config for custom MCP servers (GitHub/Linear have built-in config)
 # tools:
 #   apple-reminders:
 #     response_key: reminders
@@ -85,23 +51,14 @@ sources:
 #       title: name
 #       body: notes
 
-# =============================================================================
-# REPOS - Map GitHub repos to local paths (OPTIONAL)
-#
-# GitHub presets automatically resolve the repo from each item's
-# repository.full_name field. Add entries here to map repos to local paths.
-# =============================================================================
+# Map repos to local paths
 # repos:
 #   myorg/backend:
 #     path: ~/code/backend
-#
-#   myorg/frontend:
-#     path: ~/code/frontend
 
-# =============================================================================
-# Available presets (no tools config needed):
-#   github/my-issues        - Issues assigned to me
-#   github/review-requests  - PRs needing my review  
-#   github/my-prs-feedback  - My PRs with change requests
-#   linear/my-issues        - Linear tickets (requires teamId, assigneeId)
-# =============================================================================
+# Cleanup config (optional, sensible defaults)
+# cleanup:
+#   ttl_days: 30
+
+# Available presets: github/my-issues, github/review-requests,
+# github/my-prs-feedback, linear/my-issues

package/examples/templates/agent-planning.md

@@ -0,0 +1,8 @@
+Help me with this task: {name}
+
+Research and provide:
+1. **Specific recommendations** - Product links, services, or solutions that fit my needs
+2. **Key considerations** - What should I know before deciding or acting?
+3. **Next steps** - What's the simplest path to completing this?
+
+Use web search if needed. Be concise and actionable.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-pilot",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "type": "module",
   "main": "plugin/index.js",
   "description": "Automation daemon for OpenCode - polls for work and spawns sessions",

package/service/poll-service.js

@@ -9,7 +9,7 @@
  * 5. Track processed items to avoid duplicates
  */
 
-import { loadRepoConfig, getRepoConfig, getAllSources, getToolProviderConfig, resolveRepoForItem } from "./repo-config.js";
+import { loadRepoConfig, getRepoConfig, getAllSources, getToolProviderConfig, resolveRepoForItem, getCleanupTtlDays } from "./repo-config.js";
 import { createPoller, pollGenericSource } from "./poller.js";
 import { evaluateReadiness, sortByPriority } from "./readiness.js";
 import { executeAction, buildCommand } from "./actions.js";
@@ -113,11 +113,12 @@ export async function pollOnce(options = {}) {
     }
 
     let items = [];
+    let toolProviderConfig = null;
 
     // Fetch items from source
     if (!skipMcp) {
       try {
-        const toolProviderConfig = getToolProviderConfig(source.tool.mcp);
+        toolProviderConfig = getToolProviderConfig(source.tool.mcp);
         items = await pollGenericSource(source, { toolProviderConfig });
         debug(`Fetched ${items.length} items from ${sourceName}`);
       } catch (err) {
@@ -153,12 +154,22 @@ export async function pollOnce(options = {}) {
     const sortedItems = sortByPriority(readyItems, sortConfig);
 
     // Process ready items
+    // Get reprocess_on config from provider (e.g., ['state', 'updated_at'] for GitHub)
+    const reprocessOn = toolProviderConfig?.reprocess_on || source.reprocess_on;
+    
     debug(`Processing ${sortedItems.length} sorted items`);
     for (const item of sortedItems) {
       // Check if already processed
       if (pollerInstance && pollerInstance.isProcessed(item.id)) {
-        debug(`Skipping ${item.id} - already processed`);
-        continue;
+        // Check if item should be reprocessed (reopened, status changed, etc.)
+        if (pollerInstance.shouldReprocess(item, { reprocessOn })) {
+          debug(`Reprocessing ${item.id} - state changed`);
+          pollerInstance.clearProcessed(item.id);
+          console.log(`[poll] Reprocessing ${item.id} (reopened or updated)`);
+        } else {
+          debug(`Skipping ${item.id} - already processed`);
+          continue;
+        }
       }
 
       debug(`Executing action for ${item.id}`);
@@ -184,8 +195,15 @@ export async function pollOnce(options = {}) {
 
           if (result.success) {
             // Mark as processed to avoid re-triggering
+            // Store item state for detecting reopened/updated items
             if (pollerInstance) {
-              pollerInstance.markProcessed(item.id, { repoKey, command: result.command });
+              pollerInstance.markProcessed(item.id, { 
+                repoKey: item.repo_key, 
+                command: result.command,
+                source: sourceName,
+                itemState: item.state || item.status || null,
+                itemUpdatedAt: item.updated_at || null,
+              });
             }
             console.log(`[poll] Started session for ${item.id}`);
           } else {
@@ -200,6 +218,21 @@ export async function pollOnce(options = {}) {
         }
       }
     }
+
+    // Track which items are present/missing for reappearance detection
+    // Also clean up state entries for items no longer returned by this source
+    if (pollerInstance && items.length > 0) {
+      const currentItemIds = items.map(item => item.id);
+      
+      // Mark items as seen/unseen for reappearance detection
+      pollerInstance.markUnseen(sourceName, currentItemIds);
+      
+      // Clean up old entries (only removes entries older than 1 day)
+      const removed = pollerInstance.cleanupMissingFromSource(sourceName, currentItemIds, 1);
+      if (removed > 0) {
+        debug(`Cleaned up ${removed} stale state entries for source ${sourceName}`);
+      }
+    }
   }
 
   return results;
@@ -215,9 +248,19 @@ export async function pollOnce(options = {}) {
 export function startPolling(options = {}) {
   const { interval = DEFAULT_POLL_INTERVAL, configPath } = options;
 
+  // Load config to access cleanup settings
+  loadRepoConfig(configPath);
+
   // Initialize poller for state tracking
   pollerInstance = createPoller({ configPath });
 
+  // Clean up expired entries on startup
+  const ttlDays = getCleanupTtlDays();
+  const expiredRemoved = pollerInstance.cleanupExpired(ttlDays);
+  if (expiredRemoved > 0) {
+    console.log(`[poll] Cleaned up ${expiredRemoved} expired state entries (older than ${ttlDays} days)`);
+  }
+
   // Run first poll immediately
   pollOnce({ configPath }).catch((err) => {
     console.error("[poll] Error in poll cycle:", err.message);

package/service/poller.js

@@ -324,11 +324,84 @@ export function createPoller(options = {}) {
     markProcessed(itemId, metadata = {}) {
       processedItems.set(itemId, {
         processedAt: new Date().toISOString(),
+        lastSeenAt: new Date().toISOString(),
         ...metadata,
       });
       saveState();
     },
     
+    /**
+     * Update lastSeenAt for items currently in poll results
+     * Call this after each poll to track which items are still present
+     * @param {string[]} itemIds - IDs of items in current poll results
+     */
+    markSeen(itemIds) {
+      const now = new Date().toISOString();
+      let changed = false;
+      for (const id of itemIds) {
+        const meta = processedItems.get(id);
+        if (meta) {
+          meta.lastSeenAt = now;
+          changed = true;
+        }
+      }
+      if (changed) saveState();
+    },
+    
+    /**
+     * Check if an item has reappeared after being missing from poll results
+     * @param {string} itemId - Item ID
+     * @returns {boolean} True if item was missing and has now reappeared
+     */
+    hasReappeared(itemId) {
+      const meta = processedItems.get(itemId);
+      if (!meta) return false;
+      if (!meta.lastSeenAt) return false;
+      
+      // If lastSeenAt is older than processedAt, the item disappeared and reappeared
+      // (lastSeenAt wasn't updated because item wasn't in poll results)
+      const lastSeen = new Date(meta.lastSeenAt).getTime();
+      const processed = new Date(meta.processedAt).getTime();
+      
+      // Item reappeared if it was last seen at processing time but not since
+      // We check if there's a gap of at least one poll interval (assume 5 min)
+      // Actually, simpler: if lastSeenAt equals processedAt after multiple polls,
+      // the item was missing. But we need to track poll cycles...
+      
+      // Simpler approach: track wasSeenInLastPoll flag
+      return meta.wasUnseen === true;
+    },
+    
+    /**
+     * Mark items that were NOT in poll results as unseen
+     * @param {string} sourceName - Source name
+     * @param {string[]} currentItemIds - IDs of items in current poll results
+     */
+    markUnseen(sourceName, currentItemIds) {
+      const currentSet = new Set(currentItemIds);
+      let changed = false;
+      for (const [id, meta] of processedItems) {
+        if (meta.source === sourceName) {
+          if (currentSet.has(id)) {
+            // Item is present - clear unseen flag, update lastSeenAt
+            if (meta.wasUnseen) {
+              meta.wasUnseen = false;
+              changed = true;
+            }
+            meta.lastSeenAt = new Date().toISOString();
+            changed = true;
+          } else {
+            // Item is missing - mark as unseen
+            if (!meta.wasUnseen) {
+              meta.wasUnseen = true;
+              changed = true;
+            }
+          }
+        }
+      }
+      if (changed) saveState();
+    },
+    
     /**
      * Clear a specific item from processed state
      */
@@ -351,5 +424,144 @@ export function createPoller(options = {}) {
     getProcessedIds() {
       return Array.from(processedItems.keys());
     },
+    
+    /**
+     * Get count of processed items, optionally filtered by source
+     * @param {string} [sourceName] - Optional source filter
+     * @returns {number} Count of entries
+     */
+    getProcessedCount(sourceName) {
+      if (!sourceName) return processedItems.size;
+      let count = 0;
+      for (const [, meta] of processedItems) {
+        if (meta.source === sourceName) count++;
+      }
+      return count;
+    },
+    
+    /**
+     * Clear all entries for a specific source
+     * @param {string} sourceName - Source name
+     * @returns {number} Number of entries removed
+     */
+    clearBySource(sourceName) {
+      let removed = 0;
+      for (const [id, meta] of processedItems) {
+        if (meta.source === sourceName) {
+          processedItems.delete(id);
+          removed++;
+        }
+      }
+      if (removed > 0) saveState();
+      return removed;
+    },
+    
+    /**
+     * Remove entries older than ttlDays
+     * @param {number} [ttlDays=30] - Days before expiration
+     * @returns {number} Number of entries removed
+     */
+    cleanupExpired(ttlDays = 30) {
+      const cutoffMs = Date.now() - (ttlDays * 24 * 60 * 60 * 1000);
+      let removed = 0;
+      for (const [id, meta] of processedItems) {
+        const processedAt = new Date(meta.processedAt).getTime();
+        if (processedAt < cutoffMs) {
+          processedItems.delete(id);
+          removed++;
+        }
+      }
+      if (removed > 0) saveState();
+      return removed;
+    },
+    
+    /**
+     * Remove entries for a source that are no longer in current items
+     * Only removes entries older than minAgeDays to avoid race conditions
+     * @param {string} sourceName - Source name to clean
+     * @param {string[]} currentItemIds - Current item IDs from source
+     * @param {number} [minAgeDays=1] - Minimum age before cleanup (0 = immediate)
+     * @returns {number} Number of entries removed
+     */
+    cleanupMissingFromSource(sourceName, currentItemIds, minAgeDays = 1) {
+      const currentSet = new Set(currentItemIds);
+      // Timestamp cutoff: entries processed before this time are eligible for cleanup
+      const cutoffTimestamp = Date.now() - (minAgeDays * 24 * 60 * 60 * 1000);
+      let removed = 0;
+      for (const [id, meta] of processedItems) {
+        if (meta.source === sourceName && !currentSet.has(id)) {
+          const processedAt = new Date(meta.processedAt).getTime();
+          // Use <= to allow immediate cleanup when minAgeDays=0
+          if (processedAt <= cutoffTimestamp) {
+            processedItems.delete(id);
+            removed++;
+          }
+        }
+      }
+      if (removed > 0) saveState();
+      return removed;
+    },
+    
+    /**
+     * Check if an item should be reprocessed based on state changes
+     * Uses reprocess_on config to determine which fields to check.
+     * Also reprocesses items that reappeared after being missing.
+     * 
+     * @param {object} item - Current item from source
+     * @param {object} [options] - Options
+     * @param {string[]} [options.reprocessOn] - Fields to check for changes (e.g., ['state', 'updated_at'])
+     * @returns {boolean} True if item should be reprocessed
+     */
+    shouldReprocess(item, options = {}) {
+      if (!item.id) return false;
+      
+      const meta = processedItems.get(item.id);
+      if (!meta) return false; // Not processed before
+      
+      // Check if item reappeared after being missing (e.g., uncompleted reminder)
+      if (meta.wasUnseen) {
+        return true;
+      }
+      
+      // Get reprocess_on fields from options, default to state/status only
+      // Note: updated_at is NOT included by default because our own changes would trigger reprocessing
+      const reprocessOn = options.reprocessOn || ['state', 'status'];
+      
+      // Check each configured field for changes
+      for (const field of reprocessOn) {
+        // Handle state/status fields (detect reopening)
+        if (field === 'state' || field === 'status') {
+          const storedState = meta.itemState;
+          const currentState = item[field];
+          
+          if (storedState && currentState) {
+            const stored = storedState.toLowerCase();
+            const current = currentState.toLowerCase();
+            
+            // Reopened: was closed/merged/done, now open/in-progress
+            if ((stored === 'closed' || stored === 'merged' || stored === 'done') 
+                && (current === 'open' || current === 'in progress')) {
+              return true;
+            }
+          }
+        }
+        
+        // Handle timestamp fields (detect updates)
+        if (field === 'updated_at' || field === 'updatedAt') {
+          const storedTimestamp = meta.itemUpdatedAt;
+          const currentTimestamp = item[field] || item.updated_at || item.updatedAt;
+          
+          if (storedTimestamp && currentTimestamp) {
+            const storedTime = new Date(storedTimestamp).getTime();
+            const currentTime = new Date(currentTimestamp).getTime();
+            if (currentTime > storedTime) {
+              return true;
+            }
+          }
+        }
+      }
+      
+      return false;
+    },
   };
 }

package/service/presets/github.yaml

@@ -3,7 +3,13 @@
 # Provider-level config (applies to all GitHub presets)
 _provider:
   response_key: items
-  mappings: {}
+  mappings:
+    # Extract repo full name from repository_url (e.g., "https://api.github.com/repos/owner/repo")
+    repository_full_name: "repository_url:/repos\\/([^/]+\\/[^/]+)$/"
+  # Reprocess items when state changes (e.g., reopened issues)
+  # Note: updated_at is NOT included because our own changes would trigger reprocessing
+  reprocess_on:
+    - state        # Detect reopened (closed -> open)
 
 # Presets
 my-issues:
@@ -15,7 +21,7 @@ my-issues:
     q: "is:issue assignee:@me state:open"
   item:
     id: "{html_url}"
-  repo: "{repository.full_name}"
+  repo: "{repository_full_name}"
 
 review-requests:
   name: review-requests
@@ -26,7 +32,7 @@ review-requests:
     q: "is:pr review-requested:@me state:open"
   item:
     id: "{html_url}"
-  repo: "{repository.full_name}"
+  repo: "{repository_full_name}"
 
 my-prs-feedback:
   name: my-prs-feedback
@@ -37,4 +43,4 @@ my-prs-feedback:
     q: "is:pr author:@me state:open review:changes_requested"
   item:
     id: "{html_url}"
-  repo: "{repository.full_name}"
+  repo: "{repository_full_name}"

package/service/presets/linear.yaml

@@ -6,6 +6,10 @@ _provider:
   mappings:
     body: title
     number: "url:/([A-Z0-9]+-[0-9]+)/"
+  # Reprocess items when status regresses (e.g., Done -> In Progress)
+  # Note: updatedAt is NOT included because our own changes would trigger reprocessing
+  reprocess_on:
+    - status       # Detect status changes (Done -> In Progress)
 
 # Presets
 my-issues:

package/service/repo-config.js

@@ -301,6 +301,15 @@ export function findRepoByPath(searchPath) {
   return null;
 }
 
+/**
+ * Get cleanup TTL days from config
+ * @returns {number} TTL in days (default: 30)
+ */
+export function getCleanupTtlDays() {
+  const config = getRawConfig();
+  return config?.cleanup?.ttl_days ?? 30;
+}
+
 /**
  * Clear config cache (for testing)
  */

package/test/unit/poll-service.test.js

@@ -159,14 +159,15 @@ sources:
       loadRepoConfig(configPath);
       
       const source = getSources()[0];
+      // Item with repository_full_name (mapped from repository_url by GitHub provider)
       const item = { 
-        repository: { full_name: 'myorg/backend' },
+        repository_full_name: 'myorg/backend',
         number: 123,
         html_url: 'https://github.com/myorg/backend/issues/123'
       };
       
-      // Source should have repo field from preset
-      assert.strictEqual(source.repo, '{repository.full_name}');
+      // Source should have repo field from preset (uses mapped field)
+      assert.strictEqual(source.repo, '{repository_full_name}');
       
       // resolveRepoForItem should extract repo key from item
       const repoKeys = resolveRepoForItem(source, item);
@@ -194,8 +195,9 @@ sources:
       loadRepoConfig(configPath);
       
       const source = getSources()[0];
+      // Item with repository_full_name (mapped from repository_url by GitHub provider)
       const item = { 
-        repository: { full_name: 'unknown/repo' },
+        repository_full_name: 'unknown/repo',
         number: 456
       };
       

package/test/unit/poller.test.js

@@ -106,6 +106,428 @@ describe('poller.js', () => {
       assert.strictEqual(poller.getProcessedIds().length, 0);
       assert.strictEqual(poller.isProcessed('item-1'), false);
     });
+
+    test('clearProcessed removes a single item', async () => {
+      const { createPoller } = await import('../../service/poller.js');
+      
+      const poller = createPoller({ stateFile });
+      poller.markProcessed('item-1', { source: 'test' });
+      poller.markProcessed('item-2', { source: 'test' });
+      
+      poller.clearProcessed('item-1');
+      
+      assert.strictEqual(poller.isProcessed('item-1'), false);
+      assert.strictEqual(poller.isProcessed('item-2'), true);
+    });
+  });
+
+  describe('cleanup methods', () => {
+    test('getProcessedCount returns total count', async () => {
+      const { createPoller } = await import('../../service/poller.js');
+      
+      const poller = createPoller({ stateFile });
+      poller.markProcessed('item-1', { source: 'source-a' });
+      poller.markProcessed('item-2', { source: 'source-a' });
+      poller.markProcessed('item-3', { source: 'source-b' });
+      
+      assert.strictEqual(poller.getProcessedCount(), 3);
+    });
+
+    test('getProcessedCount filters by source', async () => {
+      const { createPoller } = await import('../../service/poller.js');
+      
+      const poller = createPoller({ stateFile });
+      poller.markProcessed('item-1', { source: 'source-a' });
+      poller.markProcessed('item-2', { source: 'source-a' });
+      poller.markProcessed('item-3', { source: 'source-b' });
+      
+      assert.strictEqual(poller.getProcessedCount('source-a'), 2);
+      assert.strictEqual(poller.getProcessedCount('source-b'), 1);
+      assert.strictEqual(poller.getProcessedCount('source-c'), 0);
+    });
+
+    test('clearBySource removes all entries for a source', async () => {
+      const { createPoller } = await import('../../service/poller.js');
+      
+      const poller = createPoller({ stateFile });
+      poller.markProcessed('item-1', { source: 'source-a' });
+      poller.markProcessed('item-2', { source: 'source-a' });
+      poller.markProcessed('item-3', { source: 'source-b' });
+      
+      const removed = poller.clearBySource('source-a');
+      
+      assert.strictEqual(removed, 2);
+      assert.strictEqual(poller.isProcessed('item-1'), false);
+      assert.strictEqual(poller.isProcessed('item-2'), false);
+      assert.strictEqual(poller.isProcessed('item-3'), true);
+    });
+
+    test('clearBySource returns 0 for unknown source', async () => {
+      const { createPoller } = await import('../../service/poller.js');
+      
+      const poller = createPoller({ stateFile });
+      poller.markProcessed('item-1', { source: 'source-a' });
+      
+      const removed = poller.clearBySource('unknown');
+      
+      assert.strictEqual(removed, 0);
+      assert.strictEqual(poller.isProcessed('item-1'), true);
+    });
+
+    test('cleanupExpired removes entries older than ttlDays', async () => {
+      const { createPoller } = await import('../../service/poller.js');
+      const { readFileSync } = await import('fs');
+      
+      const poller = createPoller({ stateFile });
+      
+      // Mark items as processed
+      poller.markProcessed('recent-item', { source: 'test' });
+      poller.markProcessed('old-item', { source: 'test' });
+      
+      // Manually modify the state file to make one item old
+      const state = JSON.parse(readFileSync(stateFile, 'utf-8'));
+      const oldDate = new Date();
+      oldDate.setDate(oldDate.getDate() - 40); // 40 days ago
+      state.processed['old-item'].processedAt = oldDate.toISOString();
+      writeFileSync(stateFile, JSON.stringify(state, null, 2));
+      
+      // Create new poller to reload state
+      const poller2 = createPoller({ stateFile });
+      const removed = poller2.cleanupExpired(30);
+      
+      assert.strictEqual(removed, 1);
+      assert.strictEqual(poller2.isProcessed('recent-item'), true);
+      assert.strictEqual(poller2.isProcessed('old-item'), false);
+    });
+
+    test('cleanupExpired uses default ttlDays of 30', async () => {
+      const { createPoller } = await import('../../service/poller.js');
+      const { readFileSync } = await import('fs');
+      
+      const poller = createPoller({ stateFile });
+      poller.markProcessed('item-25-days', { source: 'test' });
+      poller.markProcessed('item-35-days', { source: 'test' });
+      
+      // Modify state file
+      const state = JSON.parse(readFileSync(stateFile, 'utf-8'));
+      const date25 = new Date();
+      date25.setDate(date25.getDate() - 25);
+      const date35 = new Date();
+      date35.setDate(date35.getDate() - 35);
+      state.processed['item-25-days'].processedAt = date25.toISOString();
+      state.processed['item-35-days'].processedAt = date35.toISOString();
+      writeFileSync(stateFile, JSON.stringify(state, null, 2));
+      
+      const poller2 = createPoller({ stateFile });
+      const removed = poller2.cleanupExpired(); // No argument = default 30
+      
+      assert.strictEqual(removed, 1);
+      assert.strictEqual(poller2.isProcessed('item-25-days'), true);
+      assert.strictEqual(poller2.isProcessed('item-35-days'), false);
+    });
+
+    test('cleanupMissingFromSource removes stale entries for a source', async () => {
+      const { createPoller } = await import('../../service/poller.js');
+      const { readFileSync } = await import('fs');
+      
+      const poller = createPoller({ stateFile });
+      poller.markProcessed('item-1', { source: 'test-source' });
+      poller.markProcessed('item-2', { source: 'test-source' });
+      poller.markProcessed('item-3', { source: 'other-source' });
+      
+      // Make items old enough to be cleaned (older than minAgeDays)
+      const state = JSON.parse(readFileSync(stateFile, 'utf-8'));
+      const oldDate = new Date();
+      oldDate.setDate(oldDate.getDate() - 2); // 2 days ago
+      for (const id of Object.keys(state.processed)) {
+        state.processed[id].processedAt = oldDate.toISOString();
+      }
+      writeFileSync(stateFile, JSON.stringify(state, null, 2));
+      
+      const poller2 = createPoller({ stateFile });
+      // Current items only has item-1 (item-2 is missing from source)
+      const removed = poller2.cleanupMissingFromSource('test-source', ['item-1'], 1);
+      
+      assert.strictEqual(removed, 1); // item-2 removed
+      assert.strictEqual(poller2.isProcessed('item-1'), true);
+      assert.strictEqual(poller2.isProcessed('item-2'), false);
+      assert.strictEqual(poller2.isProcessed('item-3'), true); // different source
+    });
+
+    test('cleanupMissingFromSource respects minAgeDays', async () => {
+      const { createPoller } = await import('../../service/poller.js');
+      
+      const poller = createPoller({ stateFile });
+      poller.markProcessed('item-1', { source: 'test-source' });
+      poller.markProcessed('item-2', { source: 'test-source' });
+      
+      // Items are fresh (just processed), so minAgeDays=1 should protect them
+      const removed = poller.cleanupMissingFromSource('test-source', ['item-1'], 1);
+      
+      assert.strictEqual(removed, 0); // item-2 NOT removed (too recent)
+      assert.strictEqual(poller.isProcessed('item-2'), true);
+    });
+
+    test('cleanupMissingFromSource with minAgeDays=0 removes immediately', async () => {
+      const { createPoller } = await import('../../service/poller.js');
+      
+      const poller = createPoller({ stateFile });
+      poller.markProcessed('item-1', { source: 'test-source' });
+      poller.markProcessed('item-2', { source: 'test-source' });
+      
+      // minAgeDays=0 removes even fresh items
+      const removed = poller.cleanupMissingFromSource('test-source', ['item-1'], 0);
+      
+      assert.strictEqual(removed, 1);
+      assert.strictEqual(poller.isProcessed('item-2'), false);
+    });
+
+    test('cleanup state persists across instances', async () => {
+      const { createPoller } = await import('../../service/poller.js');
+      
+      const poller = createPoller({ stateFile });
+      poller.markProcessed('item-1', { source: 'source-a' });
+      poller.markProcessed('item-2', { source: 'source-a' });
+      
+      poller.clearBySource('source-a');
+      
+      // Verify persistence
+      const poller2 = createPoller({ stateFile });
+      assert.strictEqual(poller2.getProcessedCount(), 0);
+    });
+  });
+
+  describe('status tracking', () => {
+    test('shouldReprocess returns false for item with same state', async () => {
+      const { createPoller } = await import('../../service/poller.js');
+      
+      const poller = createPoller({ stateFile });
+      poller.markProcessed('issue-1', { source: 'test', itemState: 'open' });
+      
+      const item = { id: 'issue-1', state: 'open' };
+      assert.strictEqual(poller.shouldReprocess(item), false);
+    });
+
+    test('shouldReprocess returns true for reopened issue (closed -> open)', async () => {
+      const { createPoller } = await import('../../service/poller.js');
+      
+      const poller = createPoller({ stateFile });
+      poller.markProcessed('issue-1', { source: 'test', itemState: 'closed' });
+      
+      const item = { id: 'issue-1', state: 'open' };
+      assert.strictEqual(poller.shouldReprocess(item), true);
+    });
+
+    test('shouldReprocess returns true for merged PR reopened', async () => {
+      const { createPoller } = await import('../../service/poller.js');
+      
+      const poller = createPoller({ stateFile });
+      poller.markProcessed('pr-1', { source: 'test', itemState: 'merged' });
+      
+      const item = { id: 'pr-1', state: 'open' };
+      assert.strictEqual(poller.shouldReprocess(item), true);
+    });
+
+    test('shouldReprocess returns false for item not in state', async () => {
+      const { createPoller } = await import('../../service/poller.js');
+      
+      const poller = createPoller({ stateFile });
+      
+      const item = { id: 'new-issue', state: 'open' };
+      assert.strictEqual(poller.shouldReprocess(item), false);
+    });
+
+    test('shouldReprocess returns false when no itemState was stored', async () => {
+      const { createPoller } = await import('../../service/poller.js');
+      
+      const poller = createPoller({ stateFile });
+      // Legacy entry without itemState
+      poller.markProcessed('issue-1', { source: 'test' });
+      
+      const item = { id: 'issue-1', state: 'open' };
+      assert.strictEqual(poller.shouldReprocess(item), false);
+    });
+
+    test('shouldReprocess uses status field for Linear items', async () => {
+      const { createPoller } = await import('../../service/poller.js');
+      
+      const poller = createPoller({ stateFile });
+      poller.markProcessed('linear-1', { source: 'test', itemState: 'Done' });
+      
+      // Linear uses 'status' field instead of 'state'
+      const item = { id: 'linear-1', status: 'In Progress' };
+      assert.strictEqual(poller.shouldReprocess(item), true);
+    });
+
+    test('shouldReprocess does NOT check updated_at by default (avoids self-triggering)', async () => {
+      const { createPoller } = await import('../../service/poller.js');
+      
+      const poller = createPoller({ stateFile });
+      poller.markProcessed('issue-1', { 
+        source: 'test', 
+        itemState: 'open',
+        itemUpdatedAt: '2026-01-01T00:00:00Z'
+      });
+      
+      // Item was updated after being processed, but state is the same
+      const item = { 
+        id: 'issue-1', 
+        state: 'open',
+        updated_at: '2026-01-05T00:00:00Z'
+      };
+      // Should NOT reprocess because updated_at is not in default reprocessOn
+      assert.strictEqual(poller.shouldReprocess(item), false);
+    });
+
+    test('shouldReprocess detects updated_at when explicitly configured', async () => {
+      const { createPoller } = await import('../../service/poller.js');
+      
+      const poller = createPoller({ stateFile });
+      poller.markProcessed('issue-1', { 
+        source: 'test', 
+        itemState: 'open',
+        itemUpdatedAt: '2026-01-01T00:00:00Z'
+      });
+      
+      const item = { 
+        id: 'issue-1', 
+        state: 'open',
+        updated_at: '2026-01-05T00:00:00Z'
+      };
+      // Should reprocess when updated_at is explicitly in reprocessOn
+      assert.strictEqual(
+        poller.shouldReprocess(item, { reprocessOn: ['updated_at'] }), 
+        true
+      );
+    });
+
+    test('shouldReprocess returns false if updated_at is same or older', async () => {
+      const { createPoller } = await import('../../service/poller.js');
+      
+      const poller = createPoller({ stateFile });
+      poller.markProcessed('issue-1', { 
+        source: 'test', 
+        itemState: 'open',
+        itemUpdatedAt: '2026-01-05T00:00:00Z'
+      });
+      
+      // Item has same updated_at
+      const item = { 
+        id: 'issue-1', 
+        state: 'open',
+        updated_at: '2026-01-05T00:00:00Z'
+      };
+      // Even with explicit config, same timestamp should not trigger
+      assert.strictEqual(
+        poller.shouldReprocess(item, { reprocessOn: ['updated_at'] }), 
+        false
+      );
+    });
+
+    test('shouldReprocess respects reprocessOn config', async () => {
+      const { createPoller } = await import('../../service/poller.js');
+      
+      const poller = createPoller({ stateFile });
+      poller.markProcessed('issue-1', { 
+        source: 'test', 
+        itemState: 'closed',
+        itemUpdatedAt: '2026-01-01T00:00:00Z'
+      });
+      
+      const item = { 
+        id: 'issue-1', 
+        state: 'open',  // Reopened
+        updated_at: '2026-01-05T00:00:00Z'  // Also updated
+      };
+      
+      // Only check updated_at, not state
+      assert.strictEqual(
+        poller.shouldReprocess(item, { reprocessOn: ['updated_at'] }), 
+        true
+      );
+      
+      // Only check state
+      assert.strictEqual(
+        poller.shouldReprocess(item, { reprocessOn: ['state'] }), 
+        true
+      );
+      
+      // Check neither (empty array)
+      assert.strictEqual(
+        poller.shouldReprocess(item, { reprocessOn: [] }), 
+        false
+      );
+    });
+
+    test('shouldReprocess handles Linear updatedAt field', async () => {
+      const { createPoller } = await import('../../service/poller.js');
+      
+      const poller = createPoller({ stateFile });
+      poller.markProcessed('linear-1', { 
+        source: 'test', 
+        itemState: 'In Progress',
+        itemUpdatedAt: '2026-01-01T00:00:00Z'
+      });
+      
+      // Linear uses camelCase updatedAt
+      const item = { 
+        id: 'linear-1', 
+        status: 'In Progress',
+        updatedAt: '2026-01-05T00:00:00Z'
+      };
+      
+      assert.strictEqual(
+        poller.shouldReprocess(item, { reprocessOn: ['updatedAt'] }), 
+        true
+      );
+    });
+
+    test('shouldReprocess returns true for reappeared item (e.g., uncompleted reminder)', async () => {
+      const { createPoller } = await import('../../service/poller.js');
+      
+      const poller = createPoller({ stateFile });
+      poller.markProcessed('reminder-1', { source: 'reminders' });
+      
+      // Simulate: item disappears from poll (completed), then reappears (uncompleted)
+      poller.markUnseen('reminders', []); // Item not in results - marked unseen
+      
+      const item = { id: 'reminder-1' };
+      assert.strictEqual(poller.shouldReprocess(item), true);
+    });
+
+    test('shouldReprocess returns false for item that was always present', async () => {
+      const { createPoller } = await import('../../service/poller.js');
+      
+      const poller = createPoller({ stateFile });
+      poller.markProcessed('reminder-1', { source: 'reminders' });
+      
+      // Item stays in poll results
+      poller.markUnseen('reminders', ['reminder-1']);
+      
+      const item = { id: 'reminder-1' };
+      assert.strictEqual(poller.shouldReprocess(item), false);
+    });
+
+    test('markUnseen tracks items across multiple polls', async () => {
+      const { createPoller } = await import('../../service/poller.js');
+      
+      const poller = createPoller({ stateFile });
+      poller.markProcessed('item-1', { source: 'test' });
+      poller.markProcessed('item-2', { source: 'test' });
+      
+      // Poll 1: both present
+      poller.markUnseen('test', ['item-1', 'item-2']);
+      assert.strictEqual(poller.shouldReprocess({ id: 'item-1' }), false);
+      assert.strictEqual(poller.shouldReprocess({ id: 'item-2' }), false);
+      
+      // Poll 2: item-2 disappears
+      poller.markUnseen('test', ['item-1']);
+      assert.strictEqual(poller.shouldReprocess({ id: 'item-1' }), false);
+      assert.strictEqual(poller.shouldReprocess({ id: 'item-2' }), true);
+      
+      // Poll 3: item-2 reappears - wasUnseen flag should still be true until cleared
+      // (The flag gets cleared when shouldReprocess triggers reprocessing)
+    });
   });
 
   describe('pollGenericSource', () => {

package/test/unit/repo-config.test.js

@@ -352,7 +352,9 @@ sources: []
       
       // GitHub preset has response_key: items, user config doesn't override it
       assert.strictEqual(toolConfig.response_key, 'items');
-      assert.deepStrictEqual(toolConfig.mappings, { url: 'html_url' });
+      // GitHub provider has mapping for repository_full_name extraction from URL
+      assert.strictEqual(toolConfig.mappings.url, 'html_url');
+      assert.ok(toolConfig.mappings.repository_full_name, 'Should have repository_full_name mapping');
     });
 
     test('getToolProviderConfig falls back to preset provider config', async () => {
@@ -628,11 +630,12 @@ sources:
       loadRepoConfig(configPath);
       const sources = getSources();
 
-      // All GitHub presets should have repo field for automatic resolution
-      const mockItem = { repository: { full_name: 'myorg/backend' } };
+      // All GitHub presets should have repo field that references repository_full_name
+      // (which is mapped from repository_url by the GitHub provider)
+      const mockItem = { repository_full_name: 'myorg/backend' };
       
       for (const source of sources) {
-        assert.strictEqual(source.repo, '{repository.full_name}', `Preset ${source.name} should have repo field`);
+        assert.strictEqual(source.repo, '{repository_full_name}', `Preset ${source.name} should have repo field`);
         const repos = resolveRepoForItem(source, mockItem);
         assert.deepStrictEqual(repos, ['myorg/backend'], `Preset ${source.name} should resolve repo from item`);
       }
@@ -651,12 +654,12 @@ sources:
       loadRepoConfig(configPath);
       const source = getSources()[0];
 
-      // Item from allowed repo should resolve
-      const allowedItem = { repository: { full_name: 'myorg/backend' } };
+      // Item from allowed repo should resolve (repository_full_name is mapped from repository_url)
+      const allowedItem = { repository_full_name: 'myorg/backend' };
       assert.deepStrictEqual(resolveRepoForItem(source, allowedItem), ['myorg/backend']);
 
       // Item from non-allowed repo should return empty (filtered out)
-      const filteredItem = { repository: { full_name: 'other/repo' } };
+      const filteredItem = { repository_full_name: 'other/repo' };
       assert.deepStrictEqual(resolveRepoForItem(source, filteredItem), []);
     });
   });
@@ -774,4 +777,48 @@ sources: []
       assert.deepStrictEqual(defaults, {});
     });
   });
+
+  describe('cleanup config', () => {
+    test('getCleanupTtlDays returns configured value', async () => {
+      writeFileSync(configPath, `
+cleanup:
+  ttl_days: 14
+
+sources: []
+`);
+
+      const { loadRepoConfig, getCleanupTtlDays } = await import('../../service/repo-config.js');
+      loadRepoConfig(configPath);
+      const ttlDays = getCleanupTtlDays();
+
+      assert.strictEqual(ttlDays, 14);
+    });
+
+    test('getCleanupTtlDays returns default 30 when not configured', async () => {
+      writeFileSync(configPath, `
+sources: []
+`);
+
+      const { loadRepoConfig, getCleanupTtlDays } = await import('../../service/repo-config.js');
+      loadRepoConfig(configPath);
+      const ttlDays = getCleanupTtlDays();
+
+      assert.strictEqual(ttlDays, 30);
+    });
+
+    test('getCleanupTtlDays returns default 30 when cleanup section exists but ttl_days not set', async () => {
+      writeFileSync(configPath, `
+cleanup:
+  some_other_option: true
+
+sources: []
+`);
+
+      const { loadRepoConfig, getCleanupTtlDays } = await import('../../service/repo-config.js');
+      loadRepoConfig(configPath);
+      const ttlDays = getCleanupTtlDays();
+
+      assert.strictEqual(ttlDays, 30);
+    });
+  });
 });