screenhand 0.3.1 → 0.3.3

package/dist/src/community/fetcher.js

@@ -4,6 +4,17 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import * as os from "node:os";
 import { RemoteCommunityAPI } from "./remote-api.js";
+/** Tools that are never allowed in community playbooks (defense in depth). */
+const BLOCKED_TOOLS = new Set([
+    "applescript", "browser_js", "browser_stealth", // code execution / anti-detection
+    "key", "launch", "focus", // RCE via terminal launch + keystroke typing
+    "memory_save", "memory_clear", "memory_snapshot", // data exfil / tampering
+    "supervisor_start", "supervisor_stop", "supervisor_install", "supervisor_uninstall",
+    "job_create", "worker_start", // persistence
+]);
+function hasBlockedTool(playbook) {
+    return playbook.steps.some((s) => BLOCKED_TOOLS.has(s.tool));
+}
 /**
  * PlaybookFetcher — fetches community playbooks from local disk
  * and optionally from a remote API (when SCREENHAND_COMMUNITY_URL is set).
@@ -36,9 +47,17 @@ export class PlaybookFetcher {
         }
         try {
             const remote = await this.remote.fetch(query);
+            // Filter remote results for blocked tools (defense in depth — local loadAll already filters)
+            const safeRemote = remote.filter((pb) => {
+                if (hasBlockedTool(pb)) {
+                    console.error(`[community] Blocked: remote playbook ${pb.id} uses restricted tool`);
+                    return false;
+                }
+                return true;
+            });
             // Deduplicate: local wins on ID collision
             const localIds = new Set(local.map((pb) => pb.id));
-            const merged = [...local, ...remote.filter((pb) => !localIds.has(pb.id))];
+            const merged = [...local, ...safeRemote.filter((pb) => !localIds.has(pb.id))];
             return this.filterAndRank(merged, query);
         }
         catch {
@@ -97,7 +116,18 @@ export class PlaybookFetcher {
                     continue;
                 try {
                     const raw = fs.readFileSync(path.join(this.repoDir, file), "utf-8");
-                    playbooks.push(JSON.parse(raw));
+                    const playbook = JSON.parse(raw);
+                    // Validate required fields
+                    if (!playbook.id || !playbook.name || !playbook.platform || !Array.isArray(playbook.steps)) {
+                        console.error(`[community] Skipping invalid playbook: ${file}`);
+                        continue;
+                    }
+                    // Block playbooks using restricted tools (defense in depth — validator also checks)
+                    if (hasBlockedTool(playbook)) {
+                        console.error(`[community] Blocked: community playbook ${file} uses restricted tool`);
+                        continue;
+                    }
+                    playbooks.push(playbook);
                 }
                 catch { /* skip malformed */ }
             }

package/dist/src/community/validator.js

@@ -6,9 +6,22 @@
  * browser_stealth (anti-detection), memory_* (data exfil),
  * supervisor_* (system control), job_* (persistence).
  */
+/**
+ * TERMINAL_BUNDLE_IDS — apps that can execute arbitrary commands.
+ * Community playbooks must not launch or focus these.
+ */
+export const TERMINAL_BUNDLE_IDS = new Set([
+    "com.apple.Terminal",
+    "com.googlecode.iterm2",
+    "net.kovidgoyal.kitty",
+    "co.zeit.hyper",
+    "com.apple.ScriptEditor2",
+    "com.microsoft.VSCode", // integrated terminal
+    "com.todesktop.230313mzl4w4u92", // Cursor (Electron, has terminal)
+]);
 const SAFE_TOOLS = new Set([
     "click", "click_text", "click_with_fallback", "type_text", "type_with_fallback",
-    "key", "drag", "scroll", "scroll_with_fallback", "focus", "launch",
+    "drag", "scroll", "scroll_with_fallback",
     "screenshot", "screenshot_file", "ocr", "ui_tree", "ui_find", "ui_press",
     "ui_set_value", "menu_click", "wait_for_state", "read_with_fallback",
     "locate_with_fallback", "select_with_fallback",
@@ -16,6 +29,7 @@ const SAFE_TOOLS = new Set([
     "browser_dom", "browser_wait", "browser_page_info", "browser_tabs",
     "browser_fill_form", "browser_human_click",
     "windows", "apps",
+    // REMOVED: "key" (char-by-char RCE via terminal), "launch" (can launch terminals), "focus" (can focus terminals)
 ]);
 /**
  * PlaybookValidator — tests a community playbook against the live app

package/dist/src/context-tracker.js

@@ -96,6 +96,10 @@ export class ContextTracker {
             this._previousPageContext = oldPage;
             this._pendingTransition = { from: oldPage, to: newPage };
         }
+        else if (!oldPage && newPage) {
+            // First page visit after app launch — record as entry point
+            this._pendingTransition = { from: "__initial__", to: newPage };
+        }
     }
     /**
      * Consume a pending page transition (returns null if no transition occurred).
@@ -132,6 +136,8 @@ export class ContextTracker {
                 return; // javascript:, data:, blob: URLs have empty hostname
             if (this.context?.domain === domain)
                 return;
+            // Flush pending learnings to the CURRENT (old) playbook before switching context
+            this.flush();
             const playbook = this.store.matchByDomain(domain);
             this.context = buildCachedContext(domain, playbook);
             return;
@@ -145,12 +151,18 @@ export class ContextTracker {
             const contextKey = `native:${bundleId}`;
             if (this.context?.domain === contextKey)
                 return;
+            // Flush pending learnings to the CURRENT (old) playbook before switching context
+            this.flush();
             const playbook = this.store.matchByBundleId(bundleId);
             this.context = buildCachedContext(contextKey, playbook);
             // Load app mastery map on bundleId change
             if (this.appMap) {
                 this.context.appMapData = this.appMap.load(bundleId) ?? null;
                 this.appMap.incrementSession(bundleId);
+                // Wire #12: flag unknown apps so intelligence wrapper can suggest scan_menu_bar
+                if (!this.context.appMapData || Object.keys(this.context.appMapData.zones).length === 0) {
+                    this.context.needsMenuScan = true;
+                }
             }
         }
     }
@@ -198,14 +210,38 @@ export class ContextTracker {
     // ═══════════════════════════════════════════════
     // 2. GET HINTS — 0-2 lines per tool call
     // ═══════════════════════════════════════════════
+    /** Wire #12: Clear the needsMenuScan hint after bootstrap succeeds */
+    clearMenuScanHint() {
+        if (this.context) {
+            this.context.needsMenuScan = false;
+        }
+    }
     /**
      * Returns relevant hints for this tool call. Max 2 hints.
      * Cost: map lookups only, ~0ms.
      */
     getHints(toolName, params) {
-        if (!this.context?.playbook)
+        if (!this.context)
             return [];
         const hints = [];
+        // Wire #12: suggest scan_menu_bar for unknown apps (no playbook required)
+        if (hints.length < 2 && this.context.needsMenuScan) {
+            hints.push("💡 New app — run scan_menu_bar(pid, bundleId, appName) to bootstrap menu knowledge");
+        }
+        // App mastery map hint (no playbook required)
+        if (hints.length < 2 && this.context.appMapData) {
+            const map = this.context.appMapData;
+            const zones = Object.keys(map.zones).length;
+            const verifiedPaths = map.navigationGraph.edges.filter((e) => e.verified).length;
+            const totalPaths = map.navigationGraph.edges.length;
+            const ratingDisplay = map.rating
+                ? (map.rating.grade === "0" ? "0" : `${map.rating.grade}${map.rating.subTier}`)
+                : map.masteryLevel.toUpperCase();
+            hints.push(`🗺 AppMap [${ratingDisplay}]: ${zones} zones, ${verifiedPaths}/${totalPaths} verified paths`);
+        }
+        // Playbook-dependent hints below
+        if (!this.context.playbook)
+            return hints;
         // Check for known errors relevant to this tool
         const errors = this.context.errorsByTool.get(toolName);
         if (errors && errors.length > 0) {
@@ -238,50 +274,43 @@ export class ContextTracker {
             }
             catch { /* skip — don't break hints for a file read error */ }
         }
-        // App mastery map hint
-        if (hints.length < 2 && this.context?.appMapData) {
-            const map = this.context.appMapData;
-            const zones = Object.keys(map.zones).length;
-            const verifiedPaths = map.navigationGraph.edges.filter((e) => e.verified).length;
-            const totalPaths = map.navigationGraph.edges.length;
-            const ratingDisplay = map.rating
-                ? (map.rating.grade === "0" ? "0" : `${map.rating.grade}${map.rating.subTier}`)
-                : map.masteryLevel.toUpperCase();
-            // Include page-specific zone info if we have page context
-            let pageInfo = "";
-            if (this._currentPageContext) {
-                const pageZoneKey = `page::${this._currentPageContext}`;
-                const pageZone = map.zones[pageZoneKey];
-                if (pageZone) {
-                    pageInfo = `, page "${this._currentPageContext}" ${pageZone.elements.length} els`;
-                }
-                else {
-                    pageInfo = `, page "${this._currentPageContext}" (new)`;
-                }
+        return hints;
+    }
+    /**
+     * L2→L1: Get a known CSS selector for a target element, if available.
+     * Returns the raw selector string for direct injection into querySelector(),
+     * not a display hint. Returns null if no matching or valid selector is found.
+     *
+     * Safety: Rejects non-CSS strings (Playwright pseudo-selectors, prose notes,
+     * AX paths) to prevent SyntaxError when passed to document.querySelector().
+     */
+    getSelector(target) {
+        if (!this.context?.allSelectors || this.context.allSelectors.size === 0)
+            return null;
+        if (!target || target.length < 2)
+            return null;
+        const targetLower = target.toLowerCase();
+        let bestMatch = null;
+        for (const [name, sel] of this.context.allSelectors) {
+            // Skip annotation keys (convention: keys starting with "_" are notes)
+            if (name.includes("._") || name.startsWith("_"))
+                continue;
+            // Validate: must look like a CSS selector, not prose or Playwright syntax
+            if (!isLikelyCSSSelector(sel))
+                continue;
+            const nameLower = name.toLowerCase();
+            const suffix = nameLower.split(".").pop() ?? "";
+            // Prefer exact suffix match over contains match
+            if (suffix === targetLower) {
+                return sel; // Exact match — return immediately
             }
-            // Navigation graph info
-            const navNodes = Object.keys(map.navigationGraph.nodes).length;
-            let navInfo = "";
-            if (navNodes > 0) {
-                navInfo = `, nav: ${navNodes} pages ${totalPaths} transitions`;
-                // Show outgoing edges from current page
-                if (this._currentPageContext) {
-                    const outgoing = map.navigationGraph.edges.filter((e) => e.from === this._currentPageContext);
-                    if (outgoing.length > 0) {
-                        const destinations = outgoing
-                            .slice(0, 3)
-                            .map((e) => `${e.to} (${e.action})`)
-                            .join(", ");
-                        const more = outgoing.length > 3 ? ` +${outgoing.length - 3} more` : "";
-                        navInfo += ` [from here: ${destinations}${more}]`;
-                    }
-                }
+            // Only fuzzy-match against the final key segment (after last "."), not the full path
+            // This prevents "ok" from matching "booking.checkout" (contains "ok" in prefix)
+            if (!bestMatch && suffix.includes(targetLower)) {
+                bestMatch = sel;
             }
-            hints.push(`🗺 Map: ${map.appName} — Rating ${ratingDisplay} ` +
-                `(${(map.confidence * 100).toFixed(0)}%, ${zones} zones, ` +
-                `${verifiedPaths}/${totalPaths} paths${pageInfo}${navInfo})`);
         }
-        return hints;
+        return bestMatch;
     }
     // ═══════════════════════════════════════════════
     // 3. COLLECT — record outcome in memory buffer
@@ -396,6 +425,26 @@ export class ContextTracker {
     getCurrentDomain() {
         return this.context?.domain ?? null;
     }
+    /**
+     * Wire F10: Get perception config hints from the active reference/playbook.
+     * Returns per-app perception interval overrides, or null if none configured.
+     */
+    getPerceptionConfig() {
+        const playbook = this.context?.playbook;
+        if (!playbook?.perceptionConfig)
+            return null;
+        const pc = playbook.perceptionConfig;
+        const result = {};
+        if (typeof pc.fastIntervalMs === "number")
+            result.fastIntervalMs = pc.fastIntervalMs;
+        if (typeof pc.mediumIntervalMs === "number")
+            result.mediumIntervalMs = pc.mediumIntervalMs;
+        if (typeof pc.slowIntervalMs === "number")
+            result.slowIntervalMs = pc.slowIntervalMs;
+        if (typeof pc.enableVision === "boolean")
+            result.enableVision = pc.enableVision;
+        return Object.keys(result).length > 0 ? result : null;
+    }
 }
 // ── Helpers ──
 function buildCachedContext(domain, playbook) {
@@ -432,6 +481,28 @@ function buildCachedContext(domain, playbook) {
     }
     return { domain, playbook, errorsByTool, allSelectors, appMapData: null };
 }
+/**
+ * Quick heuristic: does this string look like a valid CSS selector?
+ * Rejects Playwright pseudo-selectors, prose notes, AX paths, and empty strings.
+ * This is NOT a full CSS parser — it catches the common non-CSS patterns in reference files.
+ */
+function isLikelyCSSSelector(sel) {
+    if (!sel || sel.length < 2)
+        return false;
+    // Reject prose: contains spaces AND no CSS-like characters
+    if (sel.includes(" ") && !sel.includes("[") && !sel.includes(".") && !sel.includes("#") && !sel.includes(">") && !sel.includes(":"))
+        return false;
+    // Reject Playwright-specific syntax
+    if (sel.includes(">>") || sel.includes(":has-text(") || sel.includes(":text("))
+        return false;
+    // Reject strings that look like human-readable notes (start with uppercase word followed by space)
+    if (/^[A-Z][a-z]+ /.test(sel) && !sel.startsWith("["))
+        return false;
+    // Must start with a CSS-valid character: letter, #, ., [, *, :
+    if (!/^[a-zA-Z#.\[*:]/.test(sel))
+        return false;
+    return true;
+}
 function extractTarget(params) {
     for (const name of TARGET_PARAM_NAMES) {
         const val = params[name];
@@ -448,7 +519,8 @@ function findRelevantSelector(target, selectors) {
     for (const [name, sel] of selectors) {
         const nameLower = name.toLowerCase();
         // If target text matches a selector name (e.g., target="Search" matches "toolbar.search")
-        if (nameLower.includes(targetLower) || targetLower.includes(nameLower.split(".").pop() ?? "")) {
+        const suffix = nameLower.split(".").pop() ?? "";
+        if (nameLower.includes(targetLower) || (suffix && targetLower.includes(suffix))) {
             return `${name}: ${sel}`;
         }
     }

package/dist/src/ingestion/reference-merger.js

@@ -153,7 +153,9 @@ export class ReferenceMerger {
     }
     save(ref) {
         fs.mkdirSync(this.referencesDir, { recursive: true });
-        const filePath = path.join(this.referencesDir, `${ref.id}.json`);
+        // Sanitize ref.id to prevent path traversal (e.g. "../../.ssh/evil")
+        const safeId = ref.id.replace(/\.\./g, "_").replace(/[^a-zA-Z0-9._-]/g, "_");
+        const filePath = path.join(this.referencesDir, `${safeId}.json`);
         writeFileAtomicSync(filePath, JSON.stringify(ref, null, 2) + "\n");
         return filePath;
     }

package/dist/src/learning/engine.js

@@ -40,11 +40,13 @@ export class LearningEngine {
     dirty = false;
     saveTimer = null;
     constructor(config) {
+        const defaultDir = path.join(os.homedir(), ".screenhand", "learning");
+        const resolvedDir = config?.dataDir || defaultDir;
         this.config = {
             ...DEFAULT_LEARNING_CONFIG,
-            dataDir: config?.dataDir ??
-                path.join(os.homedir(), ".screenhand", "learning"),
             ...config,
+            // Ensure dataDir is never empty — applied last to override any empty string from spread
+            dataDir: resolvedDir,
         };
         this.locators = new LocatorPolicy(this.config.priorStrength);
         this.recovery = new RecoveryPolicy(this.config.priorStrength);
@@ -148,6 +150,169 @@ export class LearningEngine {
     recommendNextNavigation(bundleId, fromNode) {
         return this.topology.recommend(bundleId, fromNode, this.config.minSamplesForConfidence);
     }
+    /**
+     * Wire #14: Seed TimingModel from AppMap's stored TimingProfiles.
+     * Scans known apps and feeds their timing profiles into the timing model
+     * so that adaptive budgets work from the first tool call in a new session.
+     */
+    seedTimingFromAppMap(appMap) {
+        const bundleIds = appMap.listKnownApps();
+        for (const bundleId of bundleIds) {
+            const profiles = appMap.getTimingProfile(bundleId);
+            if (profiles.length > 0) {
+                this.timing.seedFromTimingProfiles(profiles, bundleId);
+            }
+        }
+    }
+    /**
+     * Wire F7a: Seed LocatorPolicy from AppMap's verified elements.
+     * Elements with 3+ successes get seeded as known-good locators.
+     */
+    seedLocatorsFromAppMap(appMap) {
+        const bundleIds = appMap.listKnownApps();
+        for (const bundleId of bundleIds) {
+            const data = appMap.load(bundleId);
+            if (!data)
+                continue;
+            for (const zone of Object.values(data.zones)) {
+                for (const el of zone.elements) {
+                    if (el.successCount < 3)
+                        continue;
+                    const key = LocatorPolicy.makeKey(bundleId, "click");
+                    const score = (el.successCount + 2) / (el.successCount + el.failCount + 4);
+                    this.locators.seedEntry({
+                        key,
+                        locator: el.label,
+                        method: "ax",
+                        successCount: el.successCount,
+                        failCount: el.failCount,
+                        score,
+                        lastUsed: el.lastInteracted,
+                    });
+                }
+            }
+            // Wire F7b: Seed SensorPolicy from UIArchitecture
+            if (data.uiArchitecture) {
+                const arch = data.uiArchitecture;
+                const now = data.lastValidated || new Date().toISOString();
+                if (arch.axSupport === "full") {
+                    this.sensors.seedEntry({
+                        key: `${bundleId}::ax`, bundleId, sourceType: "ax",
+                        successCount: 5, failCount: 0, score: 0.85, avgLatencyMs: 50, lastUsed: now,
+                    });
+                }
+                if (arch.rendering === "web-view" || arch.rendering === "hybrid") {
+                    this.sensors.seedEntry({
+                        key: `${bundleId}::cdp`, bundleId, sourceType: "cdp",
+                        successCount: 4, failCount: 0, score: 0.8, avgLatencyMs: 10, lastUsed: now,
+                    });
+                }
+                if (arch.rendering === "custom-paint") {
+                    this.sensors.seedEntry({
+                        key: `${bundleId}::ocr`, bundleId, sourceType: "ocr",
+                        successCount: 3, failCount: 0, score: 0.7, avgLatencyMs: 600, lastUsed: now,
+                    });
+                }
+            }
+        }
+    }
+    /**
+     * Wire F6: Seed SensorPolicy from AppMap ReadySignals.
+     * Maps signal types to sensor sources and uses typicalMs as latency.
+     */
+    seedSensorsFromReadySignals(appMap) {
+        const bundleIds = appMap.listKnownApps();
+        for (const bundleId of bundleIds) {
+            const signals = appMap.getReadySignals(bundleId);
+            for (const signal of signals) {
+                if (signal.sampleCount < 3)
+                    continue;
+                let sourceType = null;
+                const sig = signal.signal.toLowerCase();
+                if (sig.includes("ax") || sig.includes("tree") || sig.includes("accessibility"))
+                    sourceType = "ax";
+                else if (sig.includes("cdp") || sig.includes("dom") || sig.includes("chrome"))
+                    sourceType = "cdp";
+                else if (sig.includes("ocr") || sig.includes("text") || sig.includes("vision"))
+                    sourceType = "ocr";
+                if (!sourceType)
+                    continue;
+                this.sensors.seedEntry({
+                    key: `${bundleId}::${sourceType}`,
+                    bundleId, sourceType,
+                    successCount: signal.sampleCount,
+                    failCount: 0,
+                    score: 0.8,
+                    avgLatencyMs: signal.typicalMs,
+                    lastUsed: signal.lastSeen,
+                });
+            }
+        }
+    }
+    /**
+     * Wire F7c: Seed PatternPolicy from AppMap contracts.
+     * Contracts with 2+ validations are seeded as known-good patterns.
+     */
+    seedPatternsFromAppMap(appMap) {
+        const bundleIds = appMap.listKnownApps();
+        for (const bundleId of bundleIds) {
+            const data = appMap.load(bundleId);
+            if (!data)
+                continue;
+            for (const zone of Object.values(data.zones)) {
+                if (!zone.contracts)
+                    continue;
+                for (const contract of zone.contracts) {
+                    if (contract.validationCount < 2)
+                        continue;
+                    const key = `${bundleId}::${contract.action}::${contract.elementLabel}`;
+                    const score = (contract.validationCount + 2) / (contract.validationCount + 4);
+                    this.patterns.seedEntry({
+                        key,
+                        bundleId,
+                        tool: contract.action,
+                        locator: contract.elementLabel,
+                        method: "ax",
+                        successCount: contract.validationCount,
+                        failCount: 0,
+                        score,
+                        lastSeen: contract.lastValidated,
+                    });
+                }
+            }
+        }
+    }
+    /**
+     * Wire F5: Seed RecoveryPolicy from AppMap contracts with undo paths.
+     * Validated undo paths become recovery strategies for dialog blockers.
+     */
+    seedRecoveryFromContracts(appMap) {
+        const bundleIds = appMap.listKnownApps();
+        for (const bundleId of bundleIds) {
+            const data = appMap.load(bundleId);
+            if (!data)
+                continue;
+            for (const zone of Object.values(data.zones)) {
+                if (!zone.contracts)
+                    continue;
+                for (const contract of zone.contracts) {
+                    if (!contract.undoPath || contract.validationCount < 2)
+                        continue;
+                    const key = `dialog::${bundleId}`;
+                    const strategyId = `undo_${contract.elementLabel}`;
+                    this.recovery.seedEntry({
+                        key,
+                        strategyId,
+                        successCount: Math.min(contract.validationCount, 5),
+                        failCount: 0,
+                        score: 0.8,
+                        avgDurationMs: 500,
+                        lastUsed: contract.lastValidated,
+                    });
+                }
+            }
+        }
+    }
     /**
      * Get a summary of learning stats for a given app.
      */
@@ -195,7 +360,30 @@ export class LearningEngine {
         this.sensors.clear();
         this.patterns.clear();
         this.topology.clear();
-        this.flush();
+        // Explicitly delete JSONL files — save() skips empty data (falsy guard),
+        // so stale files would resurrect on next init().
+        const dir = this.config.dataDir;
+        const files = [
+            "locators.jsonl",
+            "recoveries.jsonl",
+            "timings.jsonl",
+            "sensors.jsonl",
+            "patterns.jsonl",
+            "topology.jsonl",
+        ];
+        for (const file of files) {
+            try {
+                fs.unlinkSync(path.join(dir, file));
+            }
+            catch {
+                // File may not exist — that's fine
+            }
+        }
+        this.dirty = false;
+        if (this.saveTimer) {
+            clearTimeout(this.saveTimer);
+            this.saveTimer = null;
+        }
     }
     /**
      * Force save all policies to disk.
@@ -215,7 +403,6 @@ export class LearningEngine {
             this.saveTimer = null;
             if (this.dirty) {
                 this.save();
-                this.dirty = false;
             }
         }, 500);
     }
@@ -283,6 +470,9 @@ export class LearningEngine {
             if (topologyData) {
                 writeFileAtomicSync(path.join(dir, "topology.jsonl"), topologyData + "\n");
             }
+            // Only clear dirty AFTER all writes succeed — if any write throws,
+            // dirty stays true so the next scheduled save will retry
+            this.dirty = false;
         }
         catch {
             // Persistence failure is non-fatal — data stays in memory
@@ -325,11 +515,39 @@ export class LearningEngine {
         try {
             if (!fs.existsSync(filePath))
                 return [];
-            // Guard against oversized files: skip if larger than 10MB
+            // Guard against oversized files: truncate to recent entries if larger than 10MB
             const stat = fs.statSync(filePath);
             if (stat.size > 10 * 1024 * 1024) {
-                console.error(`[Learning] Skipping oversized file: ${filePath} (${stat.size} bytes)`);
-                return [];
+                console.error(`[Learning] WARN: Oversized file: ${filePath} (${(stat.size / 1024 / 1024).toFixed(1)}MB) — truncating to recent entries`);
+                // Read the last 5MB (most recent entries are at the end)
+                const fd = fs.openSync(filePath, "r");
+                const tailSize = 5 * 1024 * 1024;
+                const buf = Buffer.alloc(tailSize);
+                fs.readSync(fd, buf, 0, tailSize, stat.size - tailSize);
+                fs.closeSync(fd);
+                const tailContent = buf.toString("utf-8");
+                // Drop first partial line
+                const firstNewline = tailContent.indexOf("\n");
+                const cleanContent = firstNewline >= 0 ? tailContent.slice(firstNewline + 1) : tailContent;
+                // Overwrite with truncated content so it doesn't grow forever
+                try {
+                    writeFileAtomicSync(filePath, cleanContent);
+                }
+                catch { /* non-fatal */ }
+                const results = [];
+                const maxEntries = this.config.maxEntriesPerFile;
+                for (const line of cleanContent.split("\n")) {
+                    if (results.length >= maxEntries)
+                        break;
+                    const trimmed = line.trim();
+                    if (!trimmed)
+                        continue;
+                    try {
+                        results.push(JSON.parse(trimmed));
+                    }
+                    catch { /* skip corrupt */ }
+                }
+                return results;
             }
             const content = fs.readFileSync(filePath, "utf-8");
             const results = [];

package/dist/src/learning/locator-policy.js

@@ -87,6 +87,22 @@ export class LocatorPolicy {
         }
         return result;
     }
+    /**
+     * Seed a single entry if no real data exists for that key+locator+method.
+     * Used for cold-start bootstrap from AppMap data.
+     */
+    seedEntry(entry) {
+        const list = this.entries.get(entry.key);
+        if (list && list.some((e) => e.locator === entry.locator && e.method === entry.method)) {
+            return; // already have real data for this locator+method
+        }
+        if (!list) {
+            this.entries.set(entry.key, [{ ...entry }]);
+        }
+        else {
+            list.push({ ...entry });
+        }
+    }
     /**
      * Load entries from persisted data.
      */

package/dist/src/learning/pattern-policy.js

@@ -71,6 +71,15 @@ export class PatternPolicy {
         }
         return null;
     }
+    /**
+     * Seed a single entry if no real data exists for that key.
+     * Used for cold-start bootstrap from AppMap contracts.
+     */
+    seedEntry(entry) {
+        if (this.entries.has(entry.key))
+            return; // already have real data
+        this.entries.set(entry.key, { ...entry });
+    }
     clear() {
         this.entries.clear();
     }

package/dist/src/learning/recovery-policy.js

@@ -79,6 +79,22 @@ export class RecoveryPolicy {
         qualified.sort((a, b) => b.score - a.score);
         return qualified[0].strategyId;
     }
+    /**
+     * Seed a single entry if no real data exists for that key+strategyId.
+     * Used for cold-start bootstrap from AppMap contracts with undo paths.
+     */
+    seedEntry(entry) {
+        const list = this.entries.get(entry.key);
+        if (list && list.some((e) => e.strategyId === entry.strategyId)) {
+            return; // already have real data
+        }
+        if (!list) {
+            this.entries.set(entry.key, [{ ...entry }]);
+        }
+        else {
+            list.push({ ...entry });
+        }
+    }
     clear() {
         this.entries.clear();
     }