laminark 2.21.8 → 2.21.9

package/plugin/dist/{tool-registry-CZ3mJ4iR.mjs → tool-registry-D8un_AcG.mjs}

@@ -1,8 +1,8 @@
-import { a as isDebugEnabled } from "./config-t8LZeB-u.mjs";
+import { a as isDebugEnabled, t as getConfigDir } from "./config-t8LZeB-u.mjs";
 import Database from "better-sqlite3";
 import * as sqliteVec from "sqlite-vec";
-import { mkdirSync } from "node:fs";
-import { dirname } from "node:path";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
 import { randomBytes } from "node:crypto";
 import { z } from "zod";
 
@@ -81,6 +81,8 @@ function debugTimed(category, message, fn) {
 * Migration 018: Tool registry FTS5 + vec0 tables for hybrid search on tool descriptions.
 * Migration 019: Add status column (active/stale/demoted) to tool_registry for staleness management.
 * Migration 020: Debug path tables (debug_paths + path_waypoints) for resolution path tracking.
+* Migration 021: Thought branch tables for coherent work unit tracking.
+* Migration 022: Add trigger_hints column to tool_registry for proactive suggestion matching.
 */
 const MIGRATIONS = [
 	{
@@ -577,6 +579,60 @@ const MIGRATIONS = [
 
       CREATE INDEX IF NOT EXISTS idx_path_waypoints_path_order
         ON path_waypoints(path_id, sequence_order);
+    `
+	},
+	{
+		version: 21,
+		name: "create_thought_branch_tables",
+		up: `
+      CREATE TABLE IF NOT EXISTS thought_branches (
+        id TEXT PRIMARY KEY,
+        project_hash TEXT NOT NULL,
+        session_id TEXT,
+        status TEXT NOT NULL DEFAULT 'active'
+          CHECK(status IN ('active', 'completed', 'abandoned', 'merged')),
+        branch_type TEXT NOT NULL DEFAULT 'unknown'
+          CHECK(branch_type IN ('investigation', 'bug_fix', 'feature', 'refactor', 'research', 'unknown')),
+        arc_stage TEXT NOT NULL DEFAULT 'investigation'
+          CHECK(arc_stage IN ('investigation', 'diagnosis', 'planning', 'execution', 'verification', 'completed')),
+        title TEXT,
+        summary TEXT,
+        parent_branch_id TEXT REFERENCES thought_branches(id),
+        linked_debug_path_id TEXT,
+        trigger_source TEXT,
+        trigger_observation_id TEXT,
+        observation_count INTEGER NOT NULL DEFAULT 0,
+        tool_pattern TEXT DEFAULT '{}',
+        started_at TEXT NOT NULL DEFAULT (datetime('now')),
+        ended_at TEXT,
+        created_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+
+      CREATE TABLE IF NOT EXISTS branch_observations (
+        branch_id TEXT NOT NULL REFERENCES thought_branches(id) ON DELETE CASCADE,
+        observation_id TEXT NOT NULL,
+        sequence_order INTEGER NOT NULL,
+        tool_name TEXT,
+        arc_stage_at_add TEXT,
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        PRIMARY KEY (branch_id, observation_id)
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_thought_branches_project_status
+        ON thought_branches(project_hash, status);
+      CREATE INDEX IF NOT EXISTS idx_thought_branches_session
+        ON thought_branches(session_id);
+      CREATE INDEX IF NOT EXISTS idx_thought_branches_started
+        ON thought_branches(started_at DESC);
+      CREATE INDEX IF NOT EXISTS idx_branch_observations_obs
+        ON branch_observations(observation_id);
+    `
+	},
+	{
+		version: 22,
+		name: "add_tool_registry_trigger_hints",
+		up: `
+      ALTER TABLE tool_registry ADD COLUMN trigger_hints TEXT;
     `
 	}
 ];
@@ -805,11 +861,32 @@ var ObservationRepository = class {
 		return rowToObservation(row);
 	}
 	/**
+	* Resolves a full or prefix ID to the full 32-char ID.
+	* Observation IDs are 32-char hex strings. Search results display only the
+	* first 8 chars via shortId(). This method allows callers to pass either
+	* a full ID or an 8-char (or any-length) prefix and get the full ID back.
+	* Returns null if no unique match is found.
+	*/
+	resolveId(id) {
+		if (id.length === 32) return id;
+		const rows = this.db.prepare("SELECT id FROM observations WHERE project_hash = ? AND id LIKE ? ESCAPE '\\' LIMIT 2").all(this.projectHash, id.replace(/[%_\\]/g, "\\$&") + "%");
+		if (rows.length === 1) return rows[0].id;
+		if (rows.length > 1) debug("obs", "Ambiguous ID prefix - multiple matches", {
+			prefix: id,
+			count: rows.length
+		});
+		return null;
+	}
+	/**
 	* Gets an observation by ID, scoped to this project.
+	* Accepts full 32-char IDs or shorter prefix strings (e.g. the 8-char
+	* display IDs shown in search results).
 	* Returns null if not found or soft-deleted.
 	*/
 	getById(id) {
-		const row = this.stmtGetById.get(id, this.projectHash);
+		const resolvedId = this.resolveId(id);
+		if (!resolvedId) return null;
+		const row = this.stmtGetById.get(resolvedId, this.projectHash);
 		return row ? rowToObservation(row) : null;
 	}
 	/**
@@ -878,20 +955,26 @@ var ObservationRepository = class {
 	}
 	/**
 	* Soft-deletes an observation by setting deleted_at.
+	* Accepts full 32-char IDs or shorter prefix strings (e.g. the 8-char
+	* display IDs shown in search results).
 	* Returns true if the observation was found and deleted.
 	*/
 	softDelete(id) {
 		debug("obs", "Soft-deleting observation", { id });
-		const result = this.stmtSoftDelete.run(id, this.projectHash);
-		debug("obs", result.changes > 0 ? "Observation soft-deleted" : "Observation not found for delete", { id });
+		const resolvedId = this.resolveId(id) ?? id;
+		const result = this.stmtSoftDelete.run(resolvedId, this.projectHash);
+		debug("obs", result.changes > 0 ? "Observation soft-deleted" : "Observation not found for delete", { id: resolvedId });
 		return result.changes > 0;
 	}
 	/**
 	* Restores a soft-deleted observation by clearing deleted_at.
+	* Accepts full 32-char IDs or shorter prefix strings (e.g. the 8-char
+	* display IDs shown in search results).
 	* Returns true if the observation was found and restored.
 	*/
 	restore(id) {
-		return this.stmtRestore.run(id, this.projectHash).changes > 0;
+		const resolvedId = this.resolveId(id) ?? id;
+		return this.stmtRestore.run(resolvedId, this.projectHash).changes > 0;
 	}
 	/**
 	* Updates the classification of an observation.
@@ -928,6 +1011,18 @@ var ObservationRepository = class {
       ORDER BY created_at ASC
       LIMIT ?
     `).all(this.projectHash, limit).map(rowToObservation);
+	}
+	/**
+	* Lists unclassified observations across ALL projects.
+	* Used by HaikuProcessor to avoid missing observations from other projects.
+	*/
+	static listAllUnclassified(db, limit = 20) {
+		return db.prepare(`
+      SELECT * FROM observations
+      WHERE classification IS NULL AND deleted_at IS NULL
+      ORDER BY created_at ASC
+      LIMIT ?
+    `).all(limit).map(rowToObservation);
 	}
 	/**
 	* Fetches observations surrounding a given timestamp for classification context.
@@ -962,11 +1057,28 @@ var ObservationRepository = class {
 	}
 	/**
 	* Gets an observation by ID, including soft-deleted observations.
+	* Accepts full 32-char IDs or shorter prefix strings (e.g. the 8-char
+	* display IDs shown in search results).
 	* Used by the recall tool for restore operations (must find purged items).
 	*/
 	getByIdIncludingDeleted(id) {
 		debug("obs", "Getting observation including deleted", { id });
-		const row = this.stmtGetByIdIncludingDeleted.get(id, this.projectHash);
+		const FULL_ID_LENGTH = 32;
+		let resolvedId;
+		if (id.length === FULL_ID_LENGTH) resolvedId = id;
+		else {
+			const rows = this.db.prepare("SELECT id FROM observations WHERE project_hash = ? AND id LIKE ? ESCAPE '\\' LIMIT 2").all(this.projectHash, id.replace(/[%_\\]/g, "\\$&") + "%");
+			if (rows.length === 0) return null;
+			if (rows.length > 1) {
+				debug("obs", "Ambiguous ID prefix for getByIdIncludingDeleted", {
+					prefix: id,
+					count: rows.length
+				});
+				return null;
+			}
+			resolvedId = rows[0].id;
+		}
+		const row = this.stmtGetByIdIncludingDeleted.get(resolvedId, this.projectHash);
 		return row ? rowToObservation(row) : null;
 	}
 	/**
@@ -1745,6 +1857,570 @@ function insertEdge(db, edge) {
 	return rowToEdge(db.prepare("SELECT * FROM graph_edges WHERE source_id = ? AND target_id = ? AND type = ?").get(edge.source_id, edge.target_id, edge.type));
 }
 
+//#endregion
+//#region src/graph/staleness.ts
+/**
+* Negation patterns: newer observation negates older one.
+* Matches when newer text contains negation keywords absent in older text
+* and both discuss similar subjects.
+*/
+const NEGATION_KEYWORDS = [
+	"not",
+	"don't",
+	"no longer",
+	"stopped",
+	"never",
+	"doesn't",
+	"won't",
+	"isn't",
+	"aren't",
+	"discontinued"
+];
+/**
+* Replacement patterns: newer observation explicitly replaces older approach.
+*/
+const REPLACEMENT_PATTERNS = [
+	/switched\s+(?:from\s+\S+\s+)?to\b/i,
+	/migrated\s+(?:from\s+\S+\s+)?to\b/i,
+	/replaced\s+(?:\S+\s+)?with\b/i,
+	/changed\s+from\b/i,
+	/moved\s+(?:from\s+\S+\s+)?to\b/i,
+	/upgraded\s+(?:from\s+\S+\s+)?to\b/i,
+	/swapped\s+(?:\S+\s+)?(?:for|with)\b/i
+];
+/**
+* Status change patterns: newer observation marks something as inactive.
+*/
+const STATUS_CHANGE_KEYWORDS = [
+	"removed",
+	"deleted",
+	"deprecated",
+	"archived",
+	"dropped",
+	"disabled",
+	"decommissioned",
+	"sunset",
+	"abandoned"
+];
+/**
+* Creates the staleness_flags table if it doesn't exist.
+* Uses a separate table rather than modifying the observations table,
+* keeping staleness metadata decoupled from core observation storage.
+*/
+function initStalenessSchema(db) {
+	db.exec(`
+    CREATE TABLE IF NOT EXISTS staleness_flags (
+      observation_id TEXT PRIMARY KEY,
+      flagged_at TEXT NOT NULL DEFAULT (datetime('now')),
+      reason TEXT NOT NULL,
+      resolved INTEGER NOT NULL DEFAULT 0
+    );
+    CREATE INDEX IF NOT EXISTS idx_staleness_resolved ON staleness_flags(resolved);
+  `);
+}
+/**
+* Detects potential staleness (contradictions) between observations
+* linked to a specific entity.
+*
+* Compares consecutive observation pairs chronologically and checks for:
+* 1. Negation patterns (newer negates older)
+* 2. Replacement patterns (newer replaces older approach)
+* 3. Status change patterns (newer marks something as inactive)
+*
+* This is DETECTION ONLY -- no data is modified.
+*
+* @param db - better-sqlite3 Database handle
+* @param entityId - Graph node ID to check observations for
+* @returns Array of StalenessReport for each detected contradiction
+*/
+function detectStaleness(db, entityId) {
+	const node = db.prepare("SELECT id, name, type, observation_ids FROM graph_nodes WHERE id = ?").get(entityId);
+	if (!node) return [];
+	const obsIds = JSON.parse(node.observation_ids);
+	if (obsIds.length < 2) return [];
+	const placeholders = obsIds.map(() => "?").join(", ");
+	const observations = db.prepare(`SELECT * FROM observations WHERE id IN (${placeholders}) AND deleted_at IS NULL ORDER BY created_at ASC`).all(...obsIds).map(rowToObservation);
+	if (observations.length < 2) return [];
+	const reports = [];
+	const now = (/* @__PURE__ */ new Date()).toISOString();
+	for (let i = 0; i < observations.length - 1; i++) {
+		const older = observations[i];
+		const newer = observations[i + 1];
+		const reason = detectContradiction(older.content, newer.content);
+		if (reason) reports.push({
+			entityId: node.id,
+			entityName: node.name,
+			entityType: node.type,
+			newerObservation: {
+				id: newer.id,
+				text: newer.content,
+				created_at: newer.createdAt
+			},
+			olderObservation: {
+				id: older.id,
+				text: older.content,
+				created_at: older.createdAt
+			},
+			reason,
+			detectedAt: now
+		});
+	}
+	return reports;
+}
+/**
+* Detects contradiction between two observation texts.
+* Returns a human-readable reason string, or null if no contradiction found.
+*/
+function detectContradiction(olderText, newerText) {
+	const olderLower = olderText.toLowerCase();
+	const newerLower = newerText.toLowerCase();
+	const negationResult = detectNegation(olderLower, newerLower);
+	if (negationResult) return negationResult;
+	const replacementResult = detectReplacement(newerLower);
+	if (replacementResult) return replacementResult;
+	const statusResult = detectStatusChange(olderLower, newerLower);
+	if (statusResult) return statusResult;
+	return null;
+}
+/**
+* Detects negation: newer text contains negation keywords that are absent
+* in the older text, suggesting the newer observation contradicts the older.
+*/
+function detectNegation(olderLower, newerLower) {
+	for (const keyword of NEGATION_KEYWORDS) if (newerLower.includes(keyword) && !olderLower.includes(keyword)) return `Newer observation contains negation ("${keyword}") not present in older observation`;
+	return null;
+}
+/**
+* Detects replacement: newer text explicitly mentions switching/replacing.
+*/
+function detectReplacement(newerLower) {
+	for (const pattern of REPLACEMENT_PATTERNS) {
+		const match = newerLower.match(pattern);
+		if (match) return `Newer observation indicates replacement ("${match[0].trim()}")`;
+	}
+	return null;
+}
+/**
+* Detects status change: newer text marks something as removed/deprecated
+* when the older text described it as active/present.
+*/
+function detectStatusChange(olderLower, newerLower) {
+	for (const keyword of STATUS_CHANGE_KEYWORDS) if (newerLower.includes(keyword) && !olderLower.includes(keyword)) return `Newer observation indicates status change ("${keyword}")`;
+	return null;
+}
+/**
+* Flags an observation as stale with an advisory reason.
+*
+* This flag is advisory -- search can use it to deprioritize but never hide
+* the observation. The observation remains fully queryable.
+*
+* Uses INSERT OR REPLACE to allow re-flagging with an updated reason.
+*
+* @param db - better-sqlite3 Database handle
+* @param observationId - ID of the observation to flag
+* @param reason - Human-readable explanation of why it's stale
+*/
+function flagStaleObservation(db, observationId, reason) {
+	initStalenessSchema(db);
+	db.prepare(`INSERT OR REPLACE INTO staleness_flags (observation_id, reason, resolved)
+     VALUES (?, ?, 0)`).run(observationId, reason);
+}
+
+//#endregion
+//#region src/config/hygiene-config.ts
+/**
+* Database Hygiene Configuration
+*
+* Controls signal weights and tier thresholds used by the hygiene
+* analyzer to score observations for deletion candidacy.
+*
+* Configuration is loaded from .laminark/hygiene.json with
+* a 5-second cache to avoid repeated disk reads.
+*/
+const DEFAULT_AUTO_CLEANUP = {
+	enabled: true,
+	tier: "high",
+	maxOrphanNodes: 500
+};
+const DEFAULTS = {
+	signalWeights: {
+		orphaned: .3,
+		islandNode: .25,
+		noiseClassified: .25,
+		shortContent: .1,
+		autoCaptured: .1,
+		stale: .1
+	},
+	tierThresholds: {
+		high: .7,
+		medium: .5
+	},
+	shortContentThreshold: 50,
+	autoCleanup: { ...DEFAULT_AUTO_CLEANUP }
+};
+const CACHE_TTL_MS = 5e3;
+let cachedConfig = null;
+let cachedAt = 0;
+function clamp(value, min, max) {
+	return Math.max(min, Math.min(max, value));
+}
+function validate(raw) {
+	const config = { ...DEFAULTS };
+	if (raw.signalWeights && typeof raw.signalWeights === "object" && !Array.isArray(raw.signalWeights)) {
+		const sw = raw.signalWeights;
+		const weights = { ...DEFAULTS.signalWeights };
+		for (const key of Object.keys(DEFAULTS.signalWeights)) if (typeof sw[key] === "number") weights[key] = clamp(sw[key], 0, 1);
+		config.signalWeights = weights;
+	}
+	if (raw.tierThresholds && typeof raw.tierThresholds === "object" && !Array.isArray(raw.tierThresholds)) {
+		const tt = raw.tierThresholds;
+		let high = typeof tt.high === "number" ? clamp(tt.high, 0, 1) : DEFAULTS.tierThresholds.high;
+		let medium = typeof tt.medium === "number" ? clamp(tt.medium, 0, 1) : DEFAULTS.tierThresholds.medium;
+		if (medium >= high) medium = Math.max(0, high - .1);
+		config.tierThresholds = {
+			high,
+			medium
+		};
+	}
+	if (typeof raw.shortContentThreshold === "number") config.shortContentThreshold = Math.max(0, Math.round(raw.shortContentThreshold));
+	if (raw.autoCleanup && typeof raw.autoCleanup === "object" && !Array.isArray(raw.autoCleanup)) {
+		const ac = raw.autoCleanup;
+		const cleanup = { ...DEFAULT_AUTO_CLEANUP };
+		if (typeof ac.enabled === "boolean") cleanup.enabled = ac.enabled;
+		if (ac.tier === "high" || ac.tier === "medium" || ac.tier === "all") cleanup.tier = ac.tier;
+		if (typeof ac.maxOrphanNodes === "number") cleanup.maxOrphanNodes = Math.max(0, Math.round(ac.maxOrphanNodes));
+		config.autoCleanup = cleanup;
+	}
+	return config;
+}
+/**
+* Loads hygiene configuration from disk with a 5-second cache.
+*/
+function loadHygieneConfig() {
+	const now = Date.now();
+	if (cachedConfig && now - cachedAt < CACHE_TTL_MS) return cachedConfig;
+	const configPath = join(getConfigDir(), "hygiene.json");
+	try {
+		const content = readFileSync(configPath, "utf-8");
+		cachedConfig = validate(JSON.parse(content));
+		debug("config", "Loaded hygiene config", { ...cachedConfig });
+	} catch {
+		cachedConfig = {
+			...DEFAULTS,
+			signalWeights: { ...DEFAULTS.signalWeights },
+			tierThresholds: { ...DEFAULTS.tierThresholds }
+		};
+	}
+	cachedAt = now;
+	return cachedConfig;
+}
+/**
+* Saves hygiene configuration to disk and invalidates cache.
+*/
+function saveHygieneConfig(config) {
+	writeFileSync(join(getConfigDir(), "hygiene.json"), JSON.stringify(config, null, 2), "utf-8");
+	cachedConfig = config;
+	cachedAt = Date.now();
+}
+/**
+* Resets hygiene config to defaults by invalidating cache.
+*/
+function resetHygieneConfig() {
+	cachedConfig = null;
+	cachedAt = 0;
+	return {
+		...DEFAULTS,
+		signalWeights: { ...DEFAULTS.signalWeights },
+		tierThresholds: { ...DEFAULTS.tierThresholds },
+		autoCleanup: { ...DEFAULT_AUTO_CLEANUP }
+	};
+}
+
+//#endregion
+//#region src/graph/hygiene-analyzer.ts
+function buildSignalLookups(db) {
+	const linkedObsIds = /* @__PURE__ */ new Set();
+	const islandObsIds = /* @__PURE__ */ new Set();
+	const allNodes = db.prepare("SELECT id, type, name, observation_ids FROM graph_nodes").all();
+	const edgeCounts = /* @__PURE__ */ new Map();
+	const edgeRows = db.prepare(`SELECT source_id AS nid, COUNT(*) AS cnt FROM graph_edges GROUP BY source_id
+     UNION ALL
+     SELECT target_id AS nid, COUNT(*) AS cnt FROM graph_edges GROUP BY target_id`).all();
+	for (const row of edgeRows) edgeCounts.set(row.nid, (edgeCounts.get(row.nid) ?? 0) + row.cnt);
+	for (const node of allNodes) {
+		let obsIds;
+		try {
+			obsIds = JSON.parse(node.observation_ids);
+		} catch {
+			continue;
+		}
+		const degree = edgeCounts.get(node.id) ?? 0;
+		for (const oid of obsIds) {
+			linkedObsIds.add(oid);
+			if (degree === 0) islandObsIds.add(oid);
+		}
+	}
+	const staleIds = /* @__PURE__ */ new Set();
+	try {
+		initStalenessSchema(db);
+		const staleRows = db.prepare("SELECT observation_id FROM staleness_flags WHERE resolved = 0").all();
+		for (const row of staleRows) staleIds.add(row.observation_id);
+	} catch {}
+	return {
+		linkedObsIds,
+		islandObsIds,
+		staleIds,
+		allNodes,
+		edgeCounts
+	};
+}
+function scoreObservation(obs, lookups, config) {
+	const weights = config.signalWeights;
+	const thresholds = config.tierThresholds;
+	const signals = {
+		orphaned: !lookups.linkedObsIds.has(obs.id),
+		islandNode: lookups.islandObsIds.has(obs.id),
+		noiseClassified: obs.classification === "noise",
+		shortContent: obs.content.length < config.shortContentThreshold,
+		autoCaptured: obs.source.startsWith("hook:"),
+		stale: lookups.staleIds.has(obs.id)
+	};
+	const confidence = (signals.orphaned ? weights.orphaned : 0) + (signals.islandNode ? weights.islandNode : 0) + (signals.noiseClassified ? weights.noiseClassified : 0) + (signals.shortContent ? weights.shortContent : 0) + (signals.autoCaptured ? weights.autoCaptured : 0) + (signals.stale ? weights.stale : 0);
+	const tier = confidence >= thresholds.high ? "high" : confidence >= thresholds.medium ? "medium" : "low";
+	return {
+		signals,
+		confidence: Math.round(confidence * 100) / 100,
+		tier
+	};
+}
+/**
+* Analyzes all active observations and scores each on deletion signals.
+* Pure read-only — no data is modified.
+*/
+function analyzeObservations(db, projectHash, opts) {
+	const limit = opts?.limit ?? 50;
+	const minTier = opts?.minTier ?? "medium";
+	const config = opts?.config ?? loadHygieneConfig();
+	debug("hygiene", "Starting analysis", {
+		projectHash,
+		sessionId: opts?.sessionId
+	});
+	let obsSql = `
+    SELECT id, content, title, source, kind, session_id, classification, created_at
+    FROM observations
+    WHERE project_hash = ? AND deleted_at IS NULL
+  `;
+	const obsParams = [projectHash];
+	if (opts?.sessionId) {
+		obsSql += " AND session_id = ?";
+		obsParams.push(opts.sessionId);
+	}
+	obsSql += " ORDER BY created_at DESC";
+	const observations = db.prepare(obsSql).all(...obsParams);
+	const lookups = buildSignalLookups(db);
+	const allCandidates = [];
+	for (const obs of observations) {
+		const { signals, confidence, tier } = scoreObservation(obs, lookups, config);
+		if (minTier === "high" && tier !== "high") continue;
+		if (minTier === "medium" && tier === "low") continue;
+		const preview = obs.content.length > 80 ? obs.content.substring(0, 80) + "..." : obs.content;
+		allCandidates.push({
+			id: obs.id,
+			shortId: obs.id.substring(0, 8),
+			sessionId: obs.session_id,
+			kind: obs.kind,
+			source: obs.source,
+			contentPreview: preview,
+			createdAt: obs.created_at,
+			signals,
+			confidence,
+			tier
+		});
+	}
+	allCandidates.sort((a, b) => b.confidence - a.confidence);
+	const activeObsIds = new Set(observations.map((o) => o.id));
+	const orphanNodes = [];
+	for (const node of lookups.allNodes) {
+		if ((lookups.edgeCounts.get(node.id) ?? 0) > 0) continue;
+		let obsIds;
+		try {
+			obsIds = JSON.parse(node.observation_ids);
+		} catch {
+			continue;
+		}
+		const allDead = obsIds.length === 0 || obsIds.every((oid) => !activeObsIds.has(oid));
+		orphanNodes.push({
+			id: node.id,
+			type: node.type,
+			name: node.name,
+			reason: allDead ? "zero edges, dead observation refs" : "zero edges (island node)"
+		});
+	}
+	const limited = allCandidates.slice(0, limit);
+	const highCount = allCandidates.filter((c) => c.tier === "high").length;
+	const mediumCount = allCandidates.filter((c) => c.tier === "medium").length;
+	const lowCount = allCandidates.filter((c) => c.tier === "low").length;
+	debug("hygiene", "Analysis complete", {
+		total: observations.length,
+		high: highCount,
+		medium: mediumCount,
+		orphanNodes: orphanNodes.length
+	});
+	return {
+		analyzedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		totalObservations: observations.length,
+		candidates: limited,
+		orphanNodes: orphanNodes.slice(0, limit),
+		summary: {
+			high: highCount,
+			medium: mediumCount,
+			low: lowCount,
+			orphanNodeCount: orphanNodes.length
+		}
+	};
+}
+/**
+* Produces a score distribution report across all observations.
+* Shows signal counts, confidence histogram, and island node summary
+* so users can tune thresholds to catch the right candidates.
+*/
+function findAnalysis(db, projectHash, config) {
+	const cfg = config ?? loadHygieneConfig();
+	const observations = db.prepare(`
+    SELECT id, content, title, source, kind, session_id, classification, created_at
+    FROM observations
+    WHERE project_hash = ? AND deleted_at IS NULL
+    ORDER BY created_at DESC
+  `).all(projectHash);
+	const lookups = buildSignalLookups(db);
+	const bySignal = {
+		orphaned: 0,
+		islandNode: 0,
+		noiseClassified: 0,
+		shortContent: 0,
+		autoCaptured: 0,
+		stale: 0
+	};
+	const buckets = new Array(10).fill(0);
+	const islandConfidences = [];
+	for (const obs of observations) {
+		const { signals, confidence } = scoreObservation(obs, lookups, cfg);
+		if (signals.orphaned) bySignal.orphaned++;
+		if (signals.islandNode) bySignal.islandNode++;
+		if (signals.noiseClassified) bySignal.noiseClassified++;
+		if (signals.shortContent) bySignal.shortContent++;
+		if (signals.autoCaptured) bySignal.autoCaptured++;
+		if (signals.stale) bySignal.stale++;
+		const bucketIdx = Math.min(Math.floor(confidence * 10), 9);
+		buckets[bucketIdx]++;
+		if (signals.islandNode) islandConfidences.push(confidence);
+	}
+	const distribution = buckets.map((count, i) => ({
+		range: `${(i / 10).toFixed(1)}-${((i + 1) / 10).toFixed(1)}`,
+		count
+	}));
+	islandConfidences.sort((a, b) => a - b);
+	const islandTotal = islandConfidences.length;
+	const minConf = islandTotal > 0 ? islandConfidences[0] : 0;
+	const maxConf = islandTotal > 0 ? islandConfidences[islandTotal - 1] : 0;
+	const medianConf = islandTotal > 0 ? islandConfidences[Math.floor(islandTotal / 2)] : 0;
+	const capturedHigh = islandConfidences.filter((c) => c >= cfg.tierThresholds.high).length;
+	const capturedMedium = islandConfidences.filter((c) => c >= cfg.tierThresholds.medium).length;
+	return {
+		total: observations.length,
+		bySignal,
+		distribution,
+		islandNodes: {
+			total: islandTotal,
+			minConfidence: Math.round(minConf * 100) / 100,
+			maxConfidence: Math.round(maxConf * 100) / 100,
+			medianConfidence: Math.round(medianConf * 100) / 100,
+			capturedAtCurrentThresholds: {
+				high: capturedHigh,
+				medium: capturedMedium,
+				all: islandTotal
+			}
+		}
+	};
+}
+/**
+* Runs automatic hygiene cleanup at session end.
+*
+* Analyzes observations and purges candidates matching the configured tier.
+* Orphan graph node removal is capped by autoCleanup.maxOrphanNodes.
+* Safe to call on every session end — skips quickly if disabled.
+*/
+function runAutoCleanup(db, projectHash, config) {
+	const cfg = config ?? loadHygieneConfig();
+	const auto = cfg.autoCleanup;
+	if (!auto.enabled) return {
+		skipped: true,
+		reason: "disabled",
+		observationsPurged: 0,
+		orphanNodesRemoved: 0
+	};
+	debug("hygiene", "Auto-cleanup starting", {
+		tier: auto.tier,
+		maxOrphanNodes: auto.maxOrphanNodes
+	});
+	const report = analyzeObservations(db, projectHash, {
+		limit: 200,
+		minTier: auto.tier === "all" ? "low" : auto.tier,
+		config: cfg
+	});
+	if (report.orphanNodes.length > auto.maxOrphanNodes) report.orphanNodes = report.orphanNodes.slice(0, auto.maxOrphanNodes);
+	if (report.candidates.length + report.orphanNodes.length === 0) {
+		debug("hygiene", "Auto-cleanup: nothing to clean");
+		return {
+			skipped: false,
+			observationsPurged: 0,
+			orphanNodesRemoved: 0
+		};
+	}
+	const result = executePurge(db, projectHash, report, auto.tier);
+	debug("hygiene", "Auto-cleanup complete", {
+		observationsPurged: result.observationsPurged,
+		orphanNodesRemoved: result.orphanNodesRemoved
+	});
+	return {
+		skipped: false,
+		...result
+	};
+}
+function executePurge(db, projectHash, report, tier) {
+	const candidateIds = report.candidates.filter((c) => {
+		if (tier === "high") return c.tier === "high";
+		if (tier === "medium") return c.tier === "high" || c.tier === "medium";
+		return true;
+	}).map((c) => c.id);
+	debug("hygiene", "Executing purge", {
+		tier,
+		candidates: candidateIds.length
+	});
+	let observationsPurged = 0;
+	const softDeleteStmt = db.prepare(`
+    UPDATE observations
+    SET deleted_at = datetime('now'), updated_at = datetime('now')
+    WHERE id = ? AND project_hash = ? AND deleted_at IS NULL
+  `);
+	return db.transaction(() => {
+		for (const id of candidateIds) {
+			const result = softDeleteStmt.run(id, projectHash);
+			observationsPurged += result.changes;
+		}
+		let orphanNodesRemoved = 0;
+		const deleteNodeStmt = db.prepare("DELETE FROM graph_nodes WHERE id = ?");
+		for (const node of report.orphanNodes) {
+			const result = deleteNodeStmt.run(node.id);
+			orphanNodesRemoved += result.changes;
+		}
+		return {
+			observationsPurged,
+			orphanNodesRemoved
+		};
+	})();
+}
+
 //#endregion
 //#region src/hooks/tool-name-parser.ts
 /**
@@ -1790,6 +2466,248 @@ function extractServerName(toolName) {
 	return null;
 }
 
+//#endregion
+//#region src/branches/branch-repository.ts
+var BranchRepository = class {
+	db;
+	projectHash;
+	stmtCreate;
+	stmtComplete;
+	stmtAbandon;
+	stmtGetActive;
+	stmtGetById;
+	stmtList;
+	stmtListByStatus;
+	stmtListByType;
+	stmtUpdateArcStage;
+	stmtUpdateToolPattern;
+	stmtUpdateClassification;
+	stmtUpdateSummary;
+	stmtIncrementObsCount;
+	stmtLinkDebugPath;
+	stmtAddObservation;
+	stmtGetObservations;
+	stmtMaxSequence;
+	stmtFindStale;
+	stmtFindUnclassified;
+	stmtFindRecentCompleted;
+	stmtFindRecentActive;
+	stmtListRecent;
+	constructor(db, projectHash) {
+		this.db = db;
+		this.projectHash = projectHash;
+		this.stmtCreate = db.prepare(`
+      INSERT INTO thought_branches
+        (id, project_hash, session_id, status, trigger_source, trigger_observation_id, started_at)
+      VALUES (?, ?, ?, 'active', ?, ?, datetime('now'))
+    `);
+		this.stmtComplete = db.prepare(`
+      UPDATE thought_branches
+      SET status = 'completed', arc_stage = 'completed', ended_at = datetime('now')
+      WHERE id = ? AND project_hash = ?
+    `);
+		this.stmtAbandon = db.prepare(`
+      UPDATE thought_branches
+      SET status = 'abandoned', ended_at = datetime('now')
+      WHERE id = ? AND project_hash = ?
+    `);
+		this.stmtGetActive = db.prepare(`
+      SELECT * FROM thought_branches
+      WHERE project_hash = ? AND status = 'active'
+      ORDER BY started_at DESC
+      LIMIT 1
+    `);
+		this.stmtGetById = db.prepare(`
+      SELECT * FROM thought_branches
+      WHERE id = ? AND project_hash = ?
+    `);
+		this.stmtList = db.prepare(`
+      SELECT * FROM thought_branches
+      WHERE project_hash = ?
+      ORDER BY started_at DESC
+      LIMIT ?
+    `);
+		this.stmtListByStatus = db.prepare(`
+      SELECT * FROM thought_branches
+      WHERE project_hash = ? AND status = ?
+      ORDER BY started_at DESC
+      LIMIT ?
+    `);
+		this.stmtListByType = db.prepare(`
+      SELECT * FROM thought_branches
+      WHERE project_hash = ? AND branch_type = ?
+      ORDER BY started_at DESC
+      LIMIT ?
+    `);
+		this.stmtUpdateArcStage = db.prepare(`
+      UPDATE thought_branches SET arc_stage = ? WHERE id = ? AND project_hash = ?
+    `);
+		this.stmtUpdateToolPattern = db.prepare(`
+      UPDATE thought_branches SET tool_pattern = ? WHERE id = ? AND project_hash = ?
+    `);
+		this.stmtUpdateClassification = db.prepare(`
+      UPDATE thought_branches SET branch_type = ?, title = ? WHERE id = ? AND project_hash = ?
+    `);
+		this.stmtUpdateSummary = db.prepare(`
+      UPDATE thought_branches SET summary = ? WHERE id = ? AND project_hash = ?
+    `);
+		this.stmtIncrementObsCount = db.prepare(`
+      UPDATE thought_branches SET observation_count = observation_count + 1 WHERE id = ? AND project_hash = ?
+    `);
+		this.stmtLinkDebugPath = db.prepare(`
+      UPDATE thought_branches SET linked_debug_path_id = ? WHERE id = ? AND project_hash = ?
+    `);
+		this.stmtAddObservation = db.prepare(`
+      INSERT OR IGNORE INTO branch_observations
+        (branch_id, observation_id, sequence_order, tool_name, arc_stage_at_add)
+      VALUES (?, ?, ?, ?, ?)
+    `);
+		this.stmtGetObservations = db.prepare(`
+      SELECT * FROM branch_observations
+      WHERE branch_id = ?
+      ORDER BY sequence_order ASC
+    `);
+		this.stmtMaxSequence = db.prepare(`
+      SELECT COALESCE(MAX(sequence_order), 0) AS max_seq FROM branch_observations
+      WHERE branch_id = ?
+    `);
+		this.stmtFindStale = db.prepare(`
+      SELECT * FROM thought_branches
+      WHERE project_hash = ? AND status = 'active'
+        AND started_at < datetime('now', '-24 hours')
+    `);
+		this.stmtFindUnclassified = db.prepare(`
+      SELECT * FROM thought_branches
+      WHERE project_hash = ? AND branch_type = 'unknown'
+        AND observation_count >= 3
+      ORDER BY started_at DESC
+      LIMIT ?
+    `);
+		this.stmtFindRecentCompleted = db.prepare(`
+      SELECT * FROM thought_branches
+      WHERE project_hash = ? AND status = 'completed' AND summary IS NULL
+        AND ended_at > datetime('now', '-1 hour')
+      ORDER BY ended_at DESC
+      LIMIT ?
+    `);
+		this.stmtFindRecentActive = db.prepare(`
+      SELECT * FROM thought_branches
+      WHERE project_hash = ? AND status = 'active'
+        AND started_at > datetime('now', '-24 hours')
+      ORDER BY started_at DESC
+      LIMIT 1
+    `);
+		this.stmtListRecent = db.prepare(`
+      SELECT * FROM thought_branches
+      WHERE project_hash = ?
+        AND started_at > datetime('now', ? || ' hours')
+      ORDER BY started_at DESC
+    `);
+	}
+	createBranch(sessionId, triggerSource, triggerObservationId) {
+		const id = randomBytes(16).toString("hex");
+		this.stmtCreate.run(id, this.projectHash, sessionId, triggerSource, triggerObservationId ?? null);
+		return this.getBranch(id);
+	}
+	completeBranch(branchId) {
+		this.stmtComplete.run(branchId, this.projectHash);
+	}
+	abandonBranch(branchId) {
+		this.stmtAbandon.run(branchId, this.projectHash);
+	}
+	getActiveBranch() {
+		const row = this.stmtGetActive.get(this.projectHash);
+		return row ? rowToBranch(row) : null;
+	}
+	getBranch(branchId) {
+		const row = this.stmtGetById.get(branchId, this.projectHash);
+		return row ? rowToBranch(row) : null;
+	}
+	listBranches(limit = 20) {
+		return this.stmtList.all(this.projectHash, limit).map(rowToBranch);
+	}
+	listByStatus(status, limit = 20) {
+		return this.stmtListByStatus.all(this.projectHash, status, limit).map(rowToBranch);
+	}
+	listByType(branchType, limit = 20) {
+		return this.stmtListByType.all(this.projectHash, branchType, limit).map(rowToBranch);
+	}
+	updateArcStage(branchId, stage) {
+		this.stmtUpdateArcStage.run(stage, branchId, this.projectHash);
+	}
+	updateToolPattern(branchId, pattern) {
+		this.stmtUpdateToolPattern.run(JSON.stringify(pattern), branchId, this.projectHash);
+	}
+	updateClassification(branchId, branchType, title) {
+		this.stmtUpdateClassification.run(branchType, title, branchId, this.projectHash);
+	}
+	updateSummary(branchId, summary) {
+		this.stmtUpdateSummary.run(summary, branchId, this.projectHash);
+	}
+	linkDebugPath(branchId, debugPathId) {
+		this.stmtLinkDebugPath.run(debugPathId, branchId, this.projectHash);
+	}
+	addObservation(branchId, observationId, toolName, arcStage) {
+		const { max_seq } = this.stmtMaxSequence.get(branchId);
+		this.stmtAddObservation.run(branchId, observationId, max_seq + 1, toolName, arcStage);
+		this.stmtIncrementObsCount.run(branchId, this.projectHash);
+	}
+	getObservations(branchId) {
+		return this.stmtGetObservations.all(branchId).map(rowToBranchObservation);
+	}
+	findStaleBranches() {
+		return this.stmtFindStale.all(this.projectHash).map(rowToBranch);
+	}
+	findUnclassifiedBranches(limit = 5) {
+		return this.stmtFindUnclassified.all(this.projectHash, limit).map(rowToBranch);
+	}
+	findRecentCompletedUnsummarized(limit = 3) {
+		return this.stmtFindRecentCompleted.all(this.projectHash, limit).map(rowToBranch);
+	}
+	findRecentActiveBranch() {
+		const row = this.stmtFindRecentActive.get(this.projectHash);
+		return row ? rowToBranch(row) : null;
+	}
+	listRecentBranches(hours) {
+		return this.stmtListRecent.all(this.projectHash, `-${hours}`).map(rowToBranch);
+	}
+};
+function rowToBranch(row) {
+	let toolPattern = {};
+	try {
+		toolPattern = JSON.parse(row.tool_pattern);
+	} catch {}
+	return {
+		id: row.id,
+		project_hash: row.project_hash,
+		session_id: row.session_id,
+		status: row.status,
+		branch_type: row.branch_type,
+		arc_stage: row.arc_stage,
+		title: row.title,
+		summary: row.summary,
+		parent_branch_id: row.parent_branch_id,
+		linked_debug_path_id: row.linked_debug_path_id,
+		trigger_source: row.trigger_source,
+		trigger_observation_id: row.trigger_observation_id,
+		observation_count: row.observation_count,
+		tool_pattern: toolPattern,
+		started_at: row.started_at,
+		ended_at: row.ended_at,
+		created_at: row.created_at
+	};
+}
+function rowToBranchObservation(row) {
+	return {
+		branch_id: row.branch_id,
+		observation_id: row.observation_id,
+		sequence_order: row.sequence_order,
+		tool_name: row.tool_name,
+		arc_stage_at_add: row.arc_stage_at_add,
+		created_at: row.created_at
+	};
+}
+
 //#endregion
 //#region src/storage/research-buffer.ts
 /**
@@ -2173,11 +3091,12 @@ var ToolRegistryRepository = class {
 		this.db = db;
 		try {
 			this.stmtUpsert = db.prepare(`
-        INSERT INTO tool_registry (name, tool_type, scope, source, project_hash, description, server_name, discovered_at)
-        VALUES (?, ?, ?, ?, ?, ?, ?, datetime('now'))
+        INSERT INTO tool_registry (name, tool_type, scope, source, project_hash, description, server_name, trigger_hints, discovered_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, datetime('now'))
         ON CONFLICT (name, COALESCE(project_hash, ''))
         DO UPDATE SET
           description = COALESCE(excluded.description, tool_registry.description),
+          trigger_hints = COALESCE(excluded.trigger_hints, tool_registry.trigger_hints),
           source = excluded.source,
           status = 'active',
           updated_at = datetime('now')
@@ -2308,7 +3227,7 @@ var ToolRegistryRepository = class {
 	*/
 	upsert(tool) {
 		try {
-			this.stmtUpsert.run(tool.name, tool.toolType, tool.scope, tool.source, tool.projectHash, tool.description, tool.serverName);
+			this.stmtUpsert.run(tool.name, tool.toolType, tool.scope, tool.source, tool.projectHash, tool.description, tool.serverName, tool.triggerHints);
 			debug("tool-registry", "Upserted tool", {
 				name: tool.name,
 				scope: tool.scope
@@ -2651,5 +3570,5 @@ var ToolRegistryRepository = class {
 };
 
 //#endregion
-export { rowToObservation as C, debug as D, runMigrations as E, debugTimed as O, ObservationRepository as S, MIGRATIONS as T, SaveGuard as _, ResearchBufferRepository as a, SearchEngine as b, inferToolType as c, getNodeByNameAndType as d, getNodesByType as f, upsertNode as g, traverseFrom as h, NotificationStore as i, countEdgesForNode as l, insertEdge as m, PathRepository as n, extractServerName as o, initGraphSchema as p, initPathSchema as r, inferScope as s, ToolRegistryRepository as t, getEdgesForNode as u, jaccardSimilarity as v, openDatabase as w, SessionRepository as x, hybridSearch as y };
-//# sourceMappingURL=tool-registry-CZ3mJ4iR.mjs.map
+export { hybridSearch as A, getNodesByType as C, upsertNode as D, traverseFrom as E, openDatabase as F, MIGRATIONS as I, runMigrations as L, SessionRepository as M, ObservationRepository as N, SaveGuard as O, rowToObservation as P, debug as R, getNodeByNameAndType as S, insertEdge as T, detectStaleness as _, ResearchBufferRepository as a, countEdgesForNode as b, inferScope as c, executePurge as d, findAnalysis as f, saveHygieneConfig as g, resetHygieneConfig as h, NotificationStore as i, SearchEngine as j, jaccardSimilarity as k, inferToolType as l, loadHygieneConfig as m, PathRepository as n, BranchRepository as o, runAutoCleanup as p, initPathSchema as r, extractServerName as s, ToolRegistryRepository as t, analyzeObservations as u, flagStaleObservation as v, initGraphSchema as w, getEdgesForNode as x, initStalenessSchema as y, debugTimed as z };
+//# sourceMappingURL=tool-registry-D8un_AcG.mjs.map