@xopcai/xopc 0.0.159 → 0.0.160

package/dist/src/proactive/insight-repository.js

@@ -0,0 +1,106 @@
+import { requireXopcDatabase } from "../storage/sqlite/connection.js";
+import { runSqliteWriteTransaction } from "../storage/sqlite/transaction.js";
+import { createHash, randomUUID } from "node:crypto";
+//#region src/proactive/insight-repository.ts
+function insightFromRow(row) {
+	return {
+		id: row.insight_id,
+		watchId: row.watch_id,
+		runId: row.run_id,
+		kind: row.kind,
+		title: row.title,
+		summary: row.summary,
+		whyItMatters: row.why_it_matters,
+		nextAction: row.next_action,
+		evidence: JSON.parse(row.evidence_json),
+		status: row.status,
+		createdAt: row.created_at,
+		updatedAt: row.updated_at
+	};
+}
+function getProactiveInsight(id) {
+	const { db } = requireXopcDatabase();
+	const row = db.prepare("SELECT * FROM proactive_insights WHERE insight_id = ?").get(id);
+	return row ? insightFromRow(row) : null;
+}
+function listProactiveInsights(options = {}) {
+	const statuses = options.status ?? ["unread", "read"];
+	if (statuses.length === 0) return [];
+	const limit = Math.max(1, Math.min(100, options.limit ?? 20));
+	const { db } = requireXopcDatabase();
+	return db.prepare(`SELECT * FROM proactive_insights
+     WHERE status IN (${statuses.map(() => "?").join(", ")})
+     ORDER BY created_at DESC LIMIT ?`).all(...statuses, limit).map(insightFromRow);
+}
+function createProactiveInsight(input) {
+	const id = randomUUID();
+	const now = input.nowMs ?? Date.now();
+	const intelligenceUpdates = input.evidence.map((item) => [
+		canonicalSource(item.source),
+		canonicalPublishedAt(item.publishedAt),
+		normalizeIdentityText(item.label)
+	]).filter(([source]) => Boolean(source)).toSorted((left, right) => JSON.stringify(left).localeCompare(JSON.stringify(right)));
+	const fingerprint = input.kind === "intelligence" && intelligenceUpdates.length > 0 ? JSON.stringify({
+		kind: input.kind,
+		updates: intelligenceUpdates
+	}) : JSON.stringify({
+		kind: input.kind,
+		title: input.title.toLocaleLowerCase().trim(),
+		summary: input.summary.toLocaleLowerCase().trim(),
+		evidence: input.evidence.map((item) => [
+			item.label.toLocaleLowerCase().trim(),
+			canonicalSource(item.source),
+			item.publishedAt ?? ""
+		])
+	});
+	const contentHash = createHash("sha256").update(fingerprint).digest("hex");
+	let created = false;
+	runSqliteWriteTransaction((db) => {
+		created = db.prepare(`INSERT OR IGNORE INTO proactive_insights (
+        insight_id, watch_id, run_id, kind, title, summary, why_it_matters,
+        next_action, evidence_json, content_hash, status, created_at, updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'unread', ?, ?)`).run(id, input.watchId, input.runId, input.kind, input.title, input.summary, input.whyItMatters, input.nextAction, JSON.stringify(input.evidence), contentHash, now, now).changes > 0;
+	});
+	return created ? listProactiveInsights({ limit: 100 }).find((item) => item.id === id) ?? null : null;
+}
+function canonicalPublishedAt(value) {
+	if (!value) return "";
+	const timestamp = Date.parse(value);
+	return Number.isFinite(timestamp) ? new Date(timestamp).toISOString() : value.trim();
+}
+function normalizeIdentityText(value) {
+	return value.trim().toLocaleLowerCase().replace(/\s+/g, " ");
+}
+function canonicalSource(source) {
+	const value = source?.trim();
+	if (!value) return "";
+	try {
+		const url = new URL(value);
+		url.hash = "";
+		for (const key of [...url.searchParams.keys()]) if (key.toLowerCase().startsWith("utm_") || key === "ref" || key === "source") url.searchParams.delete(key);
+		url.pathname = url.pathname.replace(/\/$/, "");
+		return url.toString().toLocaleLowerCase();
+	} catch {
+		return value.toLocaleLowerCase();
+	}
+}
+function setProactiveInsightStatus(id, status, nowMs = Date.now(), expectedStatus) {
+	let changed = false;
+	runSqliteWriteTransaction((db) => {
+		changed = db.prepare(`UPDATE proactive_insights SET status = ?, updated_at = ? WHERE insight_id = ?
+       ${expectedStatus ? "AND status = ?" : ""}`).run(status, nowMs, id, ...expectedStatus ? [expectedStatus] : []).changes > 0;
+	});
+	if (!changed) return null;
+	const { db } = requireXopcDatabase();
+	return insightFromRow(db.prepare("SELECT * FROM proactive_insights WHERE insight_id = ?").get(id));
+}
+function claimProactiveInsightApproval(id, nowMs = Date.now()) {
+	let claimed = false;
+	runSqliteWriteTransaction((db) => {
+		claimed = db.prepare(`UPDATE proactive_insights SET status = 'approved', updated_at = ?
+       WHERE insight_id = ? AND status = 'unread'`).run(nowMs, id).changes > 0;
+	});
+	return claimed ? getProactiveInsight(id) : null;
+}
+//#endregion
+export { claimProactiveInsightApproval, createProactiveInsight, getProactiveInsight, listProactiveInsights, setProactiveInsightStatus };

package/dist/src/proactive/run-processor.d.ts

@@ -0,0 +1,19 @@
+import type { AutomationRun } from '../automations/index.js';
+import type { ProactiveEvidence, ProactiveInsight } from './types.js';
+interface MeaningfulResult {
+    meaningful: true;
+    title: string;
+    summary: string;
+    whyItMatters: string;
+    nextAction: string;
+    evidence: ProactiveEvidence[];
+}
+export declare function parseFocusRunResult(summary: string): MeaningfulResult | {
+    meaningful: false;
+} | null;
+export declare function hasValidIntelligenceEvidence(evidence: ProactiveEvidence[]): boolean;
+export declare function processFocusAutomationRun(run: AutomationRun): {
+    handled: boolean;
+    insight?: ProactiveInsight;
+};
+export {};

package/dist/src/proactive/run-processor.js

@@ -0,0 +1,125 @@
+import { createLogger } from "../utils/logger/index.js";
+import { init_logger } from "../utils/logger.js";
+import { getFocusWatchByAutomationId, recordFocusWatchRun } from "./watch-repository.js";
+import { createProactiveInsight } from "./insight-repository.js";
+//#region src/proactive/run-processor.ts
+init_logger();
+const log = createLogger("ProactiveRunProcessor");
+function nonEmptyString(value) {
+	return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+function parseFocusRunResult(summary) {
+	const start = summary.indexOf("{");
+	const end = summary.lastIndexOf("}");
+	if (start < 0 || end <= start) return null;
+	let value;
+	try {
+		value = JSON.parse(summary.slice(start, end + 1));
+	} catch {
+		return null;
+	}
+	if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+	const result = value;
+	if (result.meaningful === false) return { meaningful: false };
+	if (result.meaningful !== true) return null;
+	const title = nonEmptyString(result.title);
+	const resultSummary = nonEmptyString(result.summary);
+	const whyItMatters = nonEmptyString(result.whyItMatters);
+	const nextAction = nonEmptyString(result.nextAction);
+	const evidence = Array.isArray(result.evidence) ? result.evidence.flatMap((item) => {
+		if (!item || typeof item !== "object" || Array.isArray(item)) return [];
+		const label = nonEmptyString(item.label);
+		const source = nonEmptyString(item.source);
+		const publishedAtValue = nonEmptyString(item.publishedAt);
+		const publishedAt = publishedAtValue && Number.isFinite(Date.parse(publishedAtValue)) ? new Date(publishedAtValue).toISOString() : null;
+		return label ? [{
+			label,
+			...source ? { source } : {},
+			...publishedAt ? { publishedAt } : {}
+		}] : [];
+	}).slice(0, 8) : [];
+	if (!title || !resultSummary || !whyItMatters || !nextAction || evidence.length === 0) return null;
+	return {
+		meaningful: true,
+		title,
+		summary: resultSummary,
+		whyItMatters,
+		nextAction,
+		evidence
+	};
+}
+function hasValidIntelligenceEvidence(evidence) {
+	return evidence.some((item) => {
+		if (!item.source || !item.publishedAt) return false;
+		try {
+			const url = new URL(item.source);
+			return (url.protocol === "https:" || url.protocol === "http:") && Number.isFinite(Date.parse(item.publishedAt));
+		} catch {
+			return false;
+		}
+	});
+}
+function processFocusAutomationRun(run) {
+	const watch = getFocusWatchByAutomationId(run.automationId);
+	if (!watch) return { handled: false };
+	if (run.status !== "succeeded" || !run.summary) {
+		recordFocusWatchRun({
+			id: watch.id,
+			runId: run.id,
+			outcome: "failed",
+			nowMs: run.endedAtMs
+		});
+		return { handled: true };
+	}
+	const result = parseFocusRunResult(run.summary);
+	if (!result) {
+		recordFocusWatchRun({
+			id: watch.id,
+			runId: run.id,
+			outcome: "failed",
+			nowMs: run.endedAtMs
+		});
+		log.warn({
+			automationId: run.automationId,
+			runId: run.id
+		}, "Focus watch returned an invalid result");
+		return { handled: true };
+	}
+	if (result.meaningful && watch.kind === "intelligence" && !hasValidIntelligenceEvidence(result.evidence)) {
+		recordFocusWatchRun({
+			id: watch.id,
+			runId: run.id,
+			outcome: "failed",
+			nowMs: run.endedAtMs
+		});
+		log.warn({
+			automationId: run.automationId,
+			runId: run.id
+		}, "Intelligence watch result lacked dated web evidence");
+		return { handled: true };
+	}
+	if (!recordFocusWatchRun({
+		id: watch.id,
+		runId: run.id,
+		outcome: result.meaningful ? "meaningful" : "empty",
+		nowMs: run.endedAtMs
+	})) return { handled: true };
+	if (!result.meaningful) return { handled: true };
+	const insight = createProactiveInsight({
+		watchId: watch.id,
+		runId: run.id,
+		kind: watch.kind,
+		title: result.title,
+		summary: result.summary,
+		whyItMatters: result.whyItMatters,
+		nextAction: result.nextAction,
+		evidence: result.evidence,
+		nowMs: run.endedAtMs
+	});
+	return insight ? {
+		handled: true,
+		insight
+	} : { handled: true };
+}
+//#endregion
+export { hasValidIntelligenceEvidence, parseFocusRunResult, processFocusAutomationRun };

package/dist/src/proactive/trial-expiry-reconciler.d.ts

@@ -0,0 +1,5 @@
+interface TrialExpiryService {
+    reconcileExpiredTrials(): Promise<number>;
+}
+export declare function startTrialExpiryReconciler(service: TrialExpiryService, intervalMs?: number): () => Promise<void>;
+export {};

package/dist/src/proactive/trial-expiry-reconciler.js

@@ -0,0 +1,30 @@
+import { createLogger } from "../utils/logger/index.js";
+import { init_logger } from "../utils/logger.js";
+//#region src/proactive/trial-expiry-reconciler.ts
+init_logger();
+const DEFAULT_RECONCILE_INTERVAL_MS = 6e4;
+const log = createLogger("FocusTrialExpiry");
+function startTrialExpiryReconciler(service, intervalMs = DEFAULT_RECONCILE_INTERVAL_MS) {
+	let stopped = false;
+	let pending = null;
+	const reconcile = () => {
+		if (stopped || pending) return;
+		pending = service.reconcileExpiredTrials().then((pausedCount) => {
+			if (pausedCount > 0) log.info({ pausedCount }, "Expired focus watch trials paused");
+		}).catch((err) => {
+			log.warn({ err }, "Focus watch trial expiry reconciliation failed");
+		}).finally(() => {
+			pending = null;
+		});
+	};
+	reconcile();
+	const timer = setInterval(reconcile, intervalMs);
+	timer.unref();
+	return async () => {
+		stopped = true;
+		clearInterval(timer);
+		await pending;
+	};
+}
+//#endregion
+export { startTrialExpiryReconciler };

package/dist/src/proactive/types.d.ts

@@ -0,0 +1,64 @@
+import type { WorkUnderstandingThread } from '../work-discovery/types.js';
+export type FocusWatchKind = 'progress' | 'staleness' | 'deadline' | 'intelligence';
+export type FocusWatchStatus = 'active' | 'paused';
+export interface FocusWatch {
+    id: string;
+    threadId: string;
+    goalId?: string;
+    automationId: string;
+    kind: FocusWatchKind;
+    status: FocusWatchStatus;
+    config: Record<string, unknown>;
+    trialEndsAt?: number;
+    lastCursor?: string;
+    lastRunAt?: number;
+    lastUsefulResultAt?: number;
+    consecutiveEmptyRuns: number;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface FocusView {
+    id: string;
+    title: string;
+    summary: string;
+    status: WorkUnderstandingThread['status'];
+    horizon: WorkUnderstandingThread['horizon'];
+    confidence: number;
+    focusScore: number;
+    userStatus: WorkUnderstandingThread['userStatus'];
+    projectIds: string[];
+    goalId?: string;
+    nextAction?: string;
+    blockedReason?: string;
+    watches: FocusWatch[];
+    lastObservedAt: number;
+}
+export type ProactiveInsightStatus = 'unread' | 'read' | 'approved' | 'dismissed';
+export interface ProactiveEvidence {
+    label: string;
+    source?: string;
+    publishedAt?: string;
+}
+export interface ProactiveInsight {
+    id: string;
+    watchId: string;
+    runId: string;
+    kind: FocusWatchKind;
+    title: string;
+    summary: string;
+    whyItMatters: string;
+    nextAction: string;
+    evidence: ProactiveEvidence[];
+    status: ProactiveInsightStatus;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface FocusCalendarSignal {
+    id: string;
+    focusId: string;
+    focusTitle: string;
+    title: string;
+    startsAt: number;
+    endsAt?: number;
+    sourceInstanceId: string;
+}

package/dist/src/proactive/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/proactive/watch-repository.d.ts

@@ -0,0 +1,28 @@
+import type { FocusWatch, FocusWatchKind, FocusWatchStatus } from './types.js';
+export declare function listFocusWatches(options?: {
+    threadId?: string;
+    status?: FocusWatchStatus;
+}): FocusWatch[];
+export declare function getFocusWatchByThreadAndKind(threadId: string, kind: FocusWatchKind): FocusWatch | null;
+export declare function getFocusWatchByAutomationId(automationId: string): FocusWatch | null;
+export declare function createFocusWatch(input: {
+    threadId: string;
+    goalId?: string;
+    automationId: string;
+    kind: FocusWatchKind;
+    config?: Record<string, unknown>;
+    trialEndsAt?: number;
+    nowMs?: number;
+}): FocusWatch;
+export declare function setFocusWatchStatus(id: string, status: FocusWatchStatus, nowMs?: number): FocusWatch | null;
+export declare function restartFocusWatchTrial(id: string, trialEndsAt: number, nowMs?: number): FocusWatch | null;
+export declare function recordFocusWatchRun(input: {
+    id: string;
+    runId: string;
+    outcome: 'meaningful' | 'empty' | 'failed';
+    nowMs?: number;
+}): FocusWatch | null;
+export declare function recordFocusWatchFeedback(id: string, useful: boolean, nowMs?: number): {
+    watch: FocusWatch;
+    consecutiveDismissed: number;
+} | null;

package/dist/src/proactive/watch-repository.js

@@ -0,0 +1,129 @@
+import { requireXopcDatabase } from "../storage/sqlite/connection.js";
+import { runSqliteWriteTransaction } from "../storage/sqlite/transaction.js";
+import { randomUUID } from "node:crypto";
+//#region src/proactive/watch-repository.ts
+function watchFromRow(row) {
+	let config = {};
+	try {
+		const parsed = JSON.parse(row.config_json);
+		if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) config = parsed;
+	} catch {
+		config = {};
+	}
+	return {
+		id: row.watch_id,
+		threadId: row.thread_id,
+		...row.goal_id ? { goalId: row.goal_id } : {},
+		automationId: row.automation_id,
+		kind: row.kind,
+		status: row.status,
+		config,
+		...row.trial_ends_at != null ? { trialEndsAt: row.trial_ends_at } : {},
+		...row.last_cursor ? { lastCursor: row.last_cursor } : {},
+		...row.last_run_at != null ? { lastRunAt: row.last_run_at } : {},
+		...row.last_useful_result_at != null ? { lastUsefulResultAt: row.last_useful_result_at } : {},
+		consecutiveEmptyRuns: row.consecutive_empty_runs,
+		createdAt: row.created_at,
+		updatedAt: row.updated_at
+	};
+}
+function listFocusWatches(options = {}) {
+	const clauses = [];
+	const values = [];
+	if (options.threadId) {
+		clauses.push("thread_id = ?");
+		values.push(options.threadId);
+	}
+	if (options.status) {
+		clauses.push("status = ?");
+		values.push(options.status);
+	}
+	const { db } = requireXopcDatabase();
+	return db.prepare(`SELECT * FROM focus_watches ${clauses.length ? `WHERE ${clauses.join(" AND ")}` : ""}
+     ORDER BY updated_at DESC`).all(...values).map(watchFromRow);
+}
+function getFocusWatchByThreadAndKind(threadId, kind) {
+	const { db } = requireXopcDatabase();
+	const row = db.prepare("SELECT * FROM focus_watches WHERE thread_id = ? AND kind = ?").get(threadId, kind);
+	return row ? watchFromRow(row) : null;
+}
+function getFocusWatchByAutomationId(automationId) {
+	const { db } = requireXopcDatabase();
+	const row = db.prepare("SELECT * FROM focus_watches WHERE automation_id = ?").get(automationId);
+	return row ? watchFromRow(row) : null;
+}
+function createFocusWatch(input) {
+	const now = input.nowMs ?? Date.now();
+	const id = randomUUID();
+	runSqliteWriteTransaction((db) => {
+		db.prepare(`INSERT INTO focus_watches (
+        watch_id, thread_id, goal_id, automation_id, kind, status, config_json,
+        trial_ends_at, consecutive_empty_runs, created_at, updated_at
+      ) VALUES (?, ?, ?, ?, ?, 'active', ?, ?, 0, ?, ?)`).run(id, input.threadId, input.goalId ?? null, input.automationId, input.kind, JSON.stringify(input.config ?? {}), input.trialEndsAt ?? null, now, now);
+	});
+	return getFocusWatchByThreadAndKind(input.threadId, input.kind);
+}
+function setFocusWatchStatus(id, status, nowMs = Date.now()) {
+	let changed = false;
+	runSqliteWriteTransaction((db) => {
+		changed = db.prepare("UPDATE focus_watches SET status = ?, updated_at = ? WHERE watch_id = ?").run(status, nowMs, id).changes > 0;
+	});
+	if (!changed) return null;
+	const { db } = requireXopcDatabase();
+	return watchFromRow(db.prepare("SELECT * FROM focus_watches WHERE watch_id = ?").get(id));
+}
+function restartFocusWatchTrial(id, trialEndsAt, nowMs = Date.now()) {
+	let changed = false;
+	runSqliteWriteTransaction((db) => {
+		changed = db.prepare(`UPDATE focus_watches
+       SET status = 'active', trial_ends_at = ?, consecutive_empty_runs = 0, updated_at = ?
+       WHERE watch_id = ?`).run(trialEndsAt, nowMs, id).changes > 0;
+	});
+	if (!changed) return null;
+	const { db } = requireXopcDatabase();
+	return watchFromRow(db.prepare("SELECT * FROM focus_watches WHERE watch_id = ?").get(id));
+}
+function recordFocusWatchRun(input) {
+	const now = input.nowMs ?? Date.now();
+	let changed = false;
+	runSqliteWriteTransaction((db) => {
+		changed = db.prepare(`UPDATE focus_watches SET
+        last_cursor = ?,
+        last_run_at = ?,
+        last_useful_result_at = CASE WHEN ? = 'meaningful' THEN ? ELSE last_useful_result_at END,
+        consecutive_empty_runs = CASE
+          WHEN ? = 'meaningful' THEN 0
+          WHEN ? = 'empty' THEN consecutive_empty_runs + 1
+          ELSE consecutive_empty_runs
+        END,
+        updated_at = ?
+       WHERE watch_id = ? AND (last_cursor IS NULL OR last_cursor <> ?)`).run(input.runId, now, input.outcome, now, input.outcome, input.outcome, now, input.id, input.runId).changes > 0;
+	});
+	if (!changed) return null;
+	return listFocusWatches().find((watch) => watch.id === input.id) ?? null;
+}
+function recordFocusWatchFeedback(id, useful, nowMs = Date.now()) {
+	const watch = listFocusWatches().find((item) => item.id === id);
+	if (!watch) return null;
+	const previous = watch.config.feedback && typeof watch.config.feedback === "object" && !Array.isArray(watch.config.feedback) ? watch.config.feedback : {};
+	const approved = typeof previous.approved === "number" ? previous.approved : 0;
+	const dismissed = typeof previous.dismissed === "number" ? previous.dismissed : 0;
+	const consecutiveDismissed = useful ? 0 : (typeof previous.consecutiveDismissed === "number" ? previous.consecutiveDismissed : 0) + 1;
+	const config = {
+		...watch.config,
+		feedback: {
+			approved: approved + (useful ? 1 : 0),
+			dismissed: dismissed + (useful ? 0 : 1),
+			consecutiveDismissed
+		}
+	};
+	runSqliteWriteTransaction((db) => {
+		db.prepare("UPDATE focus_watches SET config_json = ?, updated_at = ? WHERE watch_id = ?").run(JSON.stringify(config), nowMs, id);
+	});
+	return {
+		watch: listFocusWatches().find((item) => item.id === id),
+		consecutiveDismissed
+	};
+}
+//#endregion
+export { createFocusWatch, getFocusWatchByAutomationId, getFocusWatchByThreadAndKind, listFocusWatches, recordFocusWatchFeedback, recordFocusWatchRun, restartFocusWatchTrial, setFocusWatchStatus };

package/dist/src/storage/sqlite/knowledge-repository.d.ts

@@ -39,6 +39,7 @@ export declare function getKnowledgeConsumerWatermark(consumerId: string, source
 export declare function setKnowledgeConsumerWatermark(consumerId: string, sourceInstanceId: string, sequence: number, nowMs?: number): void;
 export declare function listKnowledgeSourceItems(options?: {
     sourceInstanceId?: string;
+    itemType?: string;
     synthesisStatus?: KnowledgeSynthesisStatus;
     includeDeleted?: boolean;
     limit?: number;

package/dist/src/storage/sqlite/knowledge-repository.js

@@ -238,6 +238,10 @@ function listKnowledgeSourceItems(options = {}) {
 		where.push("source_instance_id = ?");
 		params.push(options.sourceInstanceId);
 	}
+	if (options.itemType) {
+		where.push("item_type = ?");
+		params.push(options.itemType);
+	}
 	if (options.synthesisStatus) {
 		where.push("synthesis_status = ?");
 		params.push(options.synthesisStatus);

package/dist/src/storage/sqlite/migrations/047_work_discovery_sources.sql

@@ -0,0 +1,16 @@
+CREATE TABLE IF NOT EXISTS work_discovery_sources (
+  source_id TEXT PRIMARY KEY,
+  kind TEXT NOT NULL CHECK (kind = 'directory'),
+  root_path TEXT,
+  display_name TEXT NOT NULL,
+  status TEXT NOT NULL DEFAULT 'active' CHECK (status IN ('active', 'revoked')),
+  scope_json TEXT NOT NULL DEFAULT '{}',
+  fingerprint_json TEXT,
+  last_scanned_at INTEGER,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL,
+  UNIQUE(kind, root_path)
+);
+
+CREATE INDEX idx_work_discovery_sources_kind_status
+  ON work_discovery_sources(kind, status, updated_at DESC);

package/dist/src/storage/sqlite/migrations/048_work_understanding_investigations.sql

@@ -0,0 +1,40 @@
+CREATE TABLE IF NOT EXISTS work_understanding_investigations (
+  investigation_id TEXT PRIMARY KEY,
+  discovery_run_id TEXT NOT NULL UNIQUE,
+  status TEXT NOT NULL CHECK (status IN (
+    'planning', 'investigating', 'synthesizing', 'completed', 'failed', 'canceled'
+  )),
+  plan_json TEXT NOT NULL DEFAULT '{}',
+  budget_json TEXT NOT NULL,
+  tool_call_count INTEGER NOT NULL DEFAULT 0,
+  content_chars_read INTEGER NOT NULL DEFAULT 0,
+  error_message TEXT,
+  started_at INTEGER NOT NULL,
+  completed_at INTEGER,
+  FOREIGN KEY (discovery_run_id) REFERENCES work_discovery_runs(id) ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS work_understanding_evidence (
+  evidence_id TEXT PRIMARY KEY,
+  investigation_id TEXT NOT NULL,
+  source_grant_id TEXT,
+  project_id TEXT,
+  source_type TEXT NOT NULL CHECK (source_type IN (
+    'file', 'git', 'project_metadata', 'personal_context', 'session', 'user_statement'
+  )),
+  source_ref TEXT NOT NULL,
+  observation TEXT NOT NULL,
+  content_hash TEXT,
+  observed_at INTEGER,
+  collected_at INTEGER NOT NULL,
+  sensitivity TEXT NOT NULL DEFAULT 'normal' CHECK (sensitivity IN ('normal', 'restricted')),
+  FOREIGN KEY (investigation_id) REFERENCES work_understanding_investigations(investigation_id) ON DELETE CASCADE,
+  FOREIGN KEY (source_grant_id) REFERENCES work_discovery_sources(source_id) ON DELETE SET NULL,
+  FOREIGN KEY (project_id) REFERENCES projects(project_id) ON DELETE SET NULL
+);
+
+CREATE INDEX idx_work_understanding_evidence_investigation
+  ON work_understanding_evidence(investigation_id, collected_at ASC);
+
+CREATE INDEX idx_work_understanding_evidence_source
+  ON work_understanding_evidence(source_grant_id, source_type, collected_at DESC);

package/dist/src/storage/sqlite/migrations/049_work_understanding_threads.sql

@@ -0,0 +1,52 @@
+CREATE TABLE IF NOT EXISTS work_understanding_threads (
+  thread_id TEXT PRIMARY KEY,
+  canonical_key TEXT NOT NULL UNIQUE,
+  title TEXT NOT NULL,
+  summary TEXT NOT NULL,
+  status TEXT NOT NULL CHECK (status IN ('active', 'paused', 'blocked', 'completed', 'uncertain')),
+  horizon TEXT NOT NULL CHECK (horizon IN ('current', 'ongoing', 'long_term')),
+  focus_score REAL NOT NULL,
+  confidence REAL NOT NULL,
+  user_status TEXT NOT NULL DEFAULT 'unreviewed' CHECK (user_status IN ('unreviewed', 'confirmed', 'corrected', 'rejected')),
+  parent_thread_id TEXT,
+  first_observed_at INTEGER NOT NULL,
+  last_observed_at INTEGER NOT NULL,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL,
+  FOREIGN KEY (parent_thread_id) REFERENCES work_understanding_threads(thread_id) ON DELETE SET NULL
+);
+
+CREATE TABLE IF NOT EXISTS work_understanding_thread_projects (
+  thread_id TEXT NOT NULL,
+  project_id TEXT NOT NULL,
+  created_at INTEGER NOT NULL,
+  PRIMARY KEY (thread_id, project_id),
+  FOREIGN KEY (thread_id) REFERENCES work_understanding_threads(thread_id) ON DELETE CASCADE,
+  FOREIGN KEY (project_id) REFERENCES projects(project_id) ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS work_understanding_thread_evidence (
+  thread_id TEXT NOT NULL,
+  evidence_id TEXT NOT NULL,
+  relation TEXT NOT NULL DEFAULT 'supports' CHECK (relation IN ('supports', 'contradicts', 'context')),
+  created_at INTEGER NOT NULL,
+  PRIMARY KEY (thread_id, evidence_id),
+  FOREIGN KEY (thread_id) REFERENCES work_understanding_threads(thread_id) ON DELETE CASCADE,
+  FOREIGN KEY (evidence_id) REFERENCES work_understanding_evidence(evidence_id) ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS work_understanding_thread_feedback (
+  feedback_id TEXT PRIMARY KEY,
+  thread_id TEXT NOT NULL,
+  decision TEXT NOT NULL CHECK (decision IN ('confirmed', 'corrected', 'rejected', 'paused', 'completed')),
+  corrected_title TEXT,
+  corrected_summary TEXT,
+  created_at INTEGER NOT NULL,
+  FOREIGN KEY (thread_id) REFERENCES work_understanding_threads(thread_id) ON DELETE CASCADE
+);
+
+CREATE INDEX idx_work_understanding_threads_focus
+  ON work_understanding_threads(user_status, status, focus_score DESC, last_observed_at DESC);
+
+CREATE INDEX idx_work_understanding_thread_projects_project
+  ON work_understanding_thread_projects(project_id, created_at DESC);

package/dist/src/storage/sqlite/migrations/050_work_discovery_source_refreshes.sql

@@ -0,0 +1,15 @@
+CREATE TABLE IF NOT EXISTS work_discovery_source_refreshes (
+  refresh_id TEXT PRIMARY KEY,
+  source_id TEXT NOT NULL,
+  discovery_run_id TEXT,
+  changed INTEGER NOT NULL CHECK (changed IN (0, 1)),
+  previous_fingerprint_json TEXT,
+  current_fingerprint_json TEXT NOT NULL,
+  status TEXT NOT NULL CHECK (status IN ('checked', 'queued', 'completed', 'failed')),
+  checked_at INTEGER NOT NULL,
+  FOREIGN KEY (source_id) REFERENCES work_discovery_sources(source_id) ON DELETE CASCADE,
+  FOREIGN KEY (discovery_run_id) REFERENCES work_discovery_runs(id) ON DELETE SET NULL
+);
+
+CREATE INDEX idx_work_discovery_source_refreshes_source
+  ON work_discovery_source_refreshes(source_id, checked_at DESC);