umbrella-context 0.1.2 → 0.1.32

package/dist/repo-state.js

@@ -1,11 +1,86 @@
 import { promises as fs } from "fs";
 import path from "path";
 import { randomUUID } from "crypto";
+import { execFileSync } from "child_process";
+import { configManager } from "./config.js";
 const UM_DIR = ".um";
 const CONTEXT_FILE = "context.json";
 const PENDING_MEMORIES_FILE = "pending-memories.json";
 const PULLED_MEMORIES_FILE = "pulled-memories.json";
 const PULLED_FIXES_FILE = "pulled-fixes.json";
+const CONNECTORS_FILE = "connectors.json";
+const HUB_FILE = "hub.json";
+const CONNECTOR_RUNS_FILE = "connector-runs.json";
+const SESSION_FILE = "session.json";
+const TASKS_FILE = "tasks.json";
+const TRANSPORT_FILE = "transport.json";
+const CONTEXT_TREE_STATE_FILE = "context-tree.json";
+const HUB_ASSETS_DIR = "hub";
+const CONNECTOR_ASSETS_DIR = "connectors";
+const CONNECTOR_RUN_REPORTS_DIR = "connector-runs";
+function normalizeSessionState(state) {
+    if (!state)
+        return null;
+    return {
+        ...state,
+        commandHistory: state.commandHistory ?? [],
+        recentQueries: state.recentQueries ?? [],
+        recentCurations: state.recentCurations ?? [],
+        lastSummary: state.lastSummary ?? null,
+        currentPanel: state.currentPanel ?? null,
+        currentFocus: state.currentFocus ?? null,
+        panelHistory: state.panelHistory ?? [],
+        recentProviderIds: state.recentProviderIds ?? [],
+        recentModels: state.recentModels ?? [],
+        recentHubSlugs: state.recentHubSlugs ?? [],
+        recentConnectorSources: state.recentConnectorSources ?? [],
+        events: state.events ?? [],
+    };
+}
+function normalizeTransportState(state) {
+    if (!state)
+        return null;
+    return {
+        version: 1,
+        status: state.status ?? "idle",
+        activeTaskId: state.activeTaskId ?? null,
+        queue: state.queue ?? [],
+        stats: state.stats ?? { queued: 0, running: 0, completed: 0, failed: 0 },
+        subscriptions: state.subscriptions ?? ["task:*", "sync:*", "runtime:*", "context-tree:*"],
+        lastPushAt: state.lastPushAt ?? null,
+        lastPullAt: state.lastPullAt ?? null,
+        lastRuntimeCheckAt: state.lastRuntimeCheckAt ?? null,
+        taskKinds: state.taskKinds ?? {},
+        updatedAt: state.updatedAt ?? new Date().toISOString(),
+        events: state.events ?? [],
+    };
+}
+function buildTransportTaskKinds(tasks) {
+    return tasks.reduce((acc, task) => {
+        acc[task.kind] = (acc[task.kind] ?? 0) + 1;
+        return acc;
+    }, {});
+}
+function buildTransportStats(tasks) {
+    return tasks.reduce((acc, task) => {
+        if (task.status === "running")
+            acc.running += 1;
+        else if (task.status === "completed")
+            acc.completed += 1;
+        else if (task.status === "failed")
+            acc.failed += 1;
+        else
+            acc.queued += 1;
+        return acc;
+    }, { queued: 0, running: 0, completed: 0, failed: 0 });
+}
+function transportStatusFromTasks(tasks) {
+    if (tasks.some((task) => task.status === "running"))
+        return "running";
+    if (tasks.some((task) => task.status === "failed"))
+        return "warning";
+    return "idle";
+}
 async function pathExists(targetPath) {
     try {
         await fs.access(targetPath);
@@ -15,19 +90,71 @@ async function pathExists(targetPath) {
         return false;
     }
 }
+async function findNearestPackageRoot(startDir = process.cwd()) {
+    let current = path.resolve(startDir);
+    while (true) {
+        if (await pathExists(path.join(current, "package.json")))
+            return current;
+        const parent = path.dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
 export async function findRepoRoot(startDir = process.cwd()) {
+    try {
+        const gitRoot = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+            cwd: startDir,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        if (gitRoot)
+            return path.resolve(gitRoot);
+    }
+    catch {
+        // Fall back to local heuristics when git is unavailable or the cwd is not inside a git repo.
+    }
     let current = path.resolve(startDir);
+    let nearestPackageJsonDir = null;
     while (true) {
         if (await pathExists(path.join(current, ".git")))
             return current;
-        if (await pathExists(path.join(current, "package.json")))
-            return current;
+        if (!nearestPackageJsonDir && await pathExists(path.join(current, "package.json"))) {
+            nearestPackageJsonDir = current;
+        }
         const parent = path.dirname(current);
         if (parent === current)
-            return path.resolve(startDir);
+            return nearestPackageJsonDir ?? path.resolve(startDir);
         current = parent;
     }
 }
+async function copyMissingFiles(sourceDir, targetDir) {
+    if (!(await pathExists(sourceDir)))
+        return;
+    await fs.mkdir(targetDir, { recursive: true });
+    const entries = await fs.readdir(sourceDir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (!entry.isFile())
+            continue;
+        const source = path.join(sourceDir, entry.name);
+        const target = path.join(targetDir, entry.name);
+        if (await pathExists(target))
+            continue;
+        await fs.copyFile(source, target);
+    }
+}
+function uniqueBy(items, key) {
+    const seen = new Set();
+    const result = [];
+    for (const item of items) {
+        const nextKey = key(item);
+        if (seen.has(nextKey))
+            continue;
+        seen.add(nextKey);
+        result.push(item);
+    }
+    return result;
+}
 function getUmDir(repoRoot) {
     return path.join(repoRoot, UM_DIR);
 }
@@ -43,9 +170,35 @@ function getPulledMemoriesFile(repoRoot) {
 function getPulledFixesFile(repoRoot) {
     return path.join(getUmDir(repoRoot), PULLED_FIXES_FILE);
 }
+function getConnectorsFile(repoRoot) {
+    return path.join(getUmDir(repoRoot), CONNECTORS_FILE);
+}
+function getHubFile(repoRoot) {
+    return path.join(getUmDir(repoRoot), HUB_FILE);
+}
+function getConnectorRunsFile(repoRoot) {
+    return path.join(getUmDir(repoRoot), CONNECTOR_RUNS_FILE);
+}
+function getSessionFile(repoRoot) {
+    return path.join(getUmDir(repoRoot), SESSION_FILE);
+}
+function getTasksFile(repoRoot) {
+    return path.join(getUmDir(repoRoot), TASKS_FILE);
+}
+function getTransportFile(repoRoot) {
+    return path.join(getUmDir(repoRoot), TRANSPORT_FILE);
+}
+function getContextTreeStateFile(repoRoot) {
+    return path.join(getUmDir(repoRoot), CONTEXT_TREE_STATE_FILE);
+}
 async function ensureUmDir(repoRoot) {
     await fs.mkdir(getUmDir(repoRoot), { recursive: true });
 }
+async function ensureSubDir(repoRoot, name) {
+    const target = path.join(getUmDir(repoRoot), name);
+    await fs.mkdir(target, { recursive: true });
+    return target;
+}
 async function readJsonFile(filePath, fallback) {
     try {
         const raw = await fs.readFile(filePath, "utf8");
@@ -58,8 +211,47 @@ async function readJsonFile(filePath, fallback) {
 async function writeJsonFile(filePath, data) {
     await fs.writeFile(filePath, JSON.stringify(data, null, 2), "utf8");
 }
+async function migrateLegacyUmDir(startDir, repoRoot) {
+    const legacyRoot = await findNearestPackageRoot(startDir);
+    if (!legacyRoot || legacyRoot === repoRoot)
+        return;
+    const legacyUmDir = getUmDir(legacyRoot);
+    if (!(await pathExists(legacyUmDir)))
+        return;
+    await ensureUmDir(repoRoot);
+    const mergeArrayFile = async (fileName, fallback, key) => {
+        const legacyPath = path.join(legacyUmDir, fileName);
+        if (!(await pathExists(legacyPath)))
+            return;
+        const rootPath = path.join(getUmDir(repoRoot), fileName);
+        const legacyItems = await readJsonFile(legacyPath, fallback);
+        const rootItems = await readJsonFile(rootPath, fallback);
+        const merged = uniqueBy([...rootItems, ...legacyItems], key);
+        await writeJsonFile(rootPath, merged);
+    };
+    const rootContextPath = getContextFile(repoRoot);
+    const legacyContextPath = getContextFile(legacyRoot);
+    if (!(await pathExists(rootContextPath)) && await pathExists(legacyContextPath)) {
+        await fs.copyFile(legacyContextPath, rootContextPath);
+    }
+    await mergeArrayFile(PENDING_MEMORIES_FILE, [], (item) => item.id);
+    await mergeArrayFile(PULLED_MEMORIES_FILE, [], (item) => item.id);
+    await mergeArrayFile(PULLED_FIXES_FILE, [], (item) => item.id);
+    await mergeArrayFile(CONNECTORS_FILE, [], (item) => item.source);
+    await mergeArrayFile(HUB_FILE, [], (item) => item.slug);
+    await mergeArrayFile(CONNECTOR_RUNS_FILE, [], (item) => item.id);
+    await copyMissingFiles(path.join(legacyUmDir, HUB_ASSETS_DIR), path.join(getUmDir(repoRoot), HUB_ASSETS_DIR));
+    await copyMissingFiles(path.join(legacyUmDir, CONNECTOR_ASSETS_DIR), path.join(getUmDir(repoRoot), CONNECTOR_ASSETS_DIR));
+    await copyMissingFiles(path.join(legacyUmDir, CONNECTOR_RUN_REPORTS_DIR), path.join(getUmDir(repoRoot), CONNECTOR_RUN_REPORTS_DIR));
+    const legacySessionPath = getSessionFile(legacyRoot);
+    const rootSessionPath = getSessionFile(repoRoot);
+    if (!(await pathExists(rootSessionPath)) && await pathExists(legacySessionPath)) {
+        await fs.copyFile(legacySessionPath, rootSessionPath);
+    }
+}
 export async function ensureRepoContext(config, cwd = process.cwd()) {
     const repoRoot = await findRepoRoot(cwd);
+    await migrateLegacyUmDir(cwd, repoRoot);
     await ensureUmDir(repoRoot);
     const now = new Date().toISOString();
     const nextState = {
@@ -85,10 +277,13 @@ export async function ensureRepoContext(config, cwd = process.cwd()) {
         ...nextState,
         initializedAt: existing?.initializedAt ?? now,
     });
+    await ensureTransportState(cwd);
+    await rebuildContextTreeState(cwd);
     return repoRoot;
 }
 export async function getRepoContext(cwd = process.cwd()) {
     const repoRoot = await findRepoRoot(cwd);
+    await migrateLegacyUmDir(cwd, repoRoot);
     const state = await readJsonFile(getContextFile(repoRoot), null);
     return { repoRoot, state, umDir: getUmDir(repoRoot) };
 }
@@ -115,6 +310,7 @@ export async function addPendingMemory(input, cwd = process.cwd()) {
         ...state,
         updatedAt: new Date().toISOString(),
     }), cwd);
+    await rebuildContextTreeState(cwd);
     return entry;
 }
 export async function getPendingMemories(cwd = process.cwd()) {
@@ -124,6 +320,83 @@ export async function getPendingMemories(cwd = process.cwd()) {
 export async function clearPendingMemories(cwd = process.cwd()) {
     const { repoRoot } = await getRepoContext(cwd);
     await writeJsonFile(getPendingMemoriesFile(repoRoot), []);
+    await rebuildContextTreeState(cwd);
+}
+export async function resetRepoState(cwd = process.cwd()) {
+    const { repoRoot, state } = await getRepoContext(cwd);
+    await ensureUmDir(repoRoot);
+    await writeJsonFile(getPendingMemoriesFile(repoRoot), []);
+    await writeJsonFile(getPulledMemoriesFile(repoRoot), []);
+    await writeJsonFile(getPulledFixesFile(repoRoot), []);
+    await writeJsonFile(getConnectorsFile(repoRoot), []);
+    await writeJsonFile(getHubFile(repoRoot), []);
+    await writeJsonFile(getConnectorRunsFile(repoRoot), []);
+    await writeJsonFile(getTasksFile(repoRoot), []);
+    await writeJsonFile(getTransportFile(repoRoot), {
+        version: 1,
+        status: "idle",
+        activeTaskId: null,
+        queue: [],
+        stats: { queued: 0, running: 0, completed: 0, failed: 0 },
+        subscriptions: ["task:*", "sync:*", "runtime:*", "context-tree:*"],
+        lastPushAt: null,
+        lastPullAt: null,
+        lastRuntimeCheckAt: null,
+        taskKinds: {},
+        updatedAt: new Date().toISOString(),
+        events: [],
+    });
+    const hubDir = path.join(getUmDir(repoRoot), HUB_ASSETS_DIR);
+    const connectorDir = path.join(getUmDir(repoRoot), CONNECTOR_ASSETS_DIR);
+    const connectorReportsDir = path.join(getUmDir(repoRoot), CONNECTOR_RUN_REPORTS_DIR);
+    await fs.rm(hubDir, { recursive: true, force: true });
+    await fs.rm(connectorDir, { recursive: true, force: true });
+    await fs.rm(connectorReportsDir, { recursive: true, force: true });
+    const now = new Date().toISOString();
+    if (state) {
+        await writeJsonFile(getContextFile(repoRoot), {
+            ...state,
+            updatedAt: now,
+            lastPushAt: null,
+            lastPullAt: null,
+        });
+    }
+    const nextSession = {
+        version: 1,
+        id: randomUUID(),
+        startedAt: now,
+        updatedAt: now,
+        commandHistory: [],
+        recentQueries: [],
+        recentCurations: [],
+        lastSummary: "Reset local Context state for this repo.",
+        currentPanel: "reset",
+        currentFocus: null,
+        panelHistory: ["reset"],
+        recentProviderIds: [],
+        recentModels: [],
+        recentHubSlugs: [],
+        recentConnectorSources: [],
+        events: [
+            {
+                id: randomUUID(),
+                at: now,
+                kind: "session",
+                title: "Reset local Context state",
+                detail: "Local .um content, hub installs, connectors, runs, and pulled snapshots were cleared for this repo.",
+                panel: "reset",
+                focus: null,
+                status: "warning",
+            },
+        ],
+    };
+    await writeJsonFile(getSessionFile(repoRoot), nextSession);
+    await rebuildContextTreeState(cwd);
+    return {
+        repoRoot,
+        umDir: getUmDir(repoRoot),
+        resetAt: now,
+    };
 }
 export async function setPulledMemories(memories, cwd = process.cwd()) {
     const { repoRoot } = await getRepoContext(cwd);
@@ -134,6 +407,15 @@ export async function setPulledMemories(memories, cwd = process.cwd()) {
         updatedAt: new Date().toISOString(),
         lastPullAt: new Date().toISOString(),
     }), cwd);
+    await syncTransportFromTasks(cwd, { lastPullAt: new Date().toISOString() });
+    await recordTransportEvent({
+        kind: "sync-pull",
+        title: `Pulled ${memories.length} context entr${memories.length === 1 ? "y" : "ies"}`,
+        detail: "Updated the repo-local server snapshot.",
+        status: "success",
+        taskId: null,
+    }, cwd);
+    await rebuildContextTreeState(cwd);
 }
 export async function getPulledMemories(cwd = process.cwd()) {
     const { repoRoot } = await getRepoContext(cwd);
@@ -148,17 +430,651 @@ export async function setPulledFixes(fixes, cwd = process.cwd()) {
         updatedAt: new Date().toISOString(),
         lastPullAt: new Date().toISOString(),
     }), cwd);
+    await syncTransportFromTasks(cwd, { lastPullAt: new Date().toISOString() });
+    await rebuildContextTreeState(cwd);
 }
 export async function getPulledFixes(cwd = process.cwd()) {
     const { repoRoot } = await getRepoContext(cwd);
     return readJsonFile(getPulledFixesFile(repoRoot), []);
 }
 export async function markPushCompleted(cwd = process.cwd()) {
-    return updateRepoContext((state) => ({
+    const next = await updateRepoContext((state) => ({
         ...state,
         updatedAt: new Date().toISOString(),
         lastPushAt: new Date().toISOString(),
     }), cwd);
+    await syncTransportFromTasks(cwd, { lastPushAt: next.lastPushAt });
+    await recordTransportEvent({
+        kind: "sync-push",
+        title: "Completed Context push",
+        detail: "Local drafts were shared with the server and local push markers were updated.",
+        status: "success",
+        taskId: null,
+    }, cwd);
+    await rebuildContextTreeState(cwd);
+    return next;
+}
+export async function getInstalledConnectors(cwd = process.cwd()) {
+    const { repoRoot } = await getRepoContext(cwd);
+    const connectors = await readJsonFile(getConnectorsFile(repoRoot), []);
+    const deduped = uniqueBy(connectors, (item) => item.source);
+    if (deduped.length !== connectors.length) {
+        await writeJsonFile(getConnectorsFile(repoRoot), deduped);
+    }
+    return deduped;
+}
+export async function setInstalledConnectors(connectors, cwd = process.cwd()) {
+    const { repoRoot } = await getRepoContext(cwd);
+    await ensureUmDir(repoRoot);
+    await writeJsonFile(getConnectorsFile(repoRoot), uniqueBy(connectors, (item) => item.source));
+    await updateRepoContext((state) => ({
+        ...state,
+        updatedAt: new Date().toISOString(),
+    }), cwd);
+    await rebuildContextTreeState(cwd);
+}
+export async function getInstalledHubEntries(cwd = process.cwd()) {
+    const { repoRoot } = await getRepoContext(cwd);
+    const entries = await readJsonFile(getHubFile(repoRoot), []);
+    const deduped = uniqueBy(entries, (item) => item.slug);
+    if (deduped.length !== entries.length) {
+        await writeJsonFile(getHubFile(repoRoot), deduped);
+    }
+    return deduped;
+}
+export async function setInstalledHubEntries(entries, cwd = process.cwd()) {
+    const { repoRoot } = await getRepoContext(cwd);
+    await ensureUmDir(repoRoot);
+    await writeJsonFile(getHubFile(repoRoot), uniqueBy(entries, (item) => item.slug));
+    await updateRepoContext((state) => ({
+        ...state,
+        updatedAt: new Date().toISOString(),
+    }), cwd);
+    await rebuildContextTreeState(cwd);
+}
+export async function writeHubAsset(slug, content, cwd = process.cwd()) {
+    const { repoRoot } = await getRepoContext(cwd);
+    const dir = await ensureSubDir(repoRoot, HUB_ASSETS_DIR);
+    const filePath = path.join(dir, `${slug}.md`);
+    await fs.writeFile(filePath, content, "utf8");
+    return filePath;
+}
+export async function writeHubAssetFiles(slug, files, cwd = process.cwd()) {
+    const { repoRoot } = await getRepoContext(cwd);
+    const rootDir = await ensureSubDir(repoRoot, HUB_ASSETS_DIR);
+    const dir = path.join(rootDir, slug);
+    await fs.mkdir(dir, { recursive: true });
+    const written = [];
+    for (const file of files) {
+        const filePath = path.join(dir, file.name);
+        await fs.writeFile(filePath, file.content, "utf8");
+        written.push(filePath);
+    }
+    return written;
+}
+export async function writeConnectorAsset(source, content, cwd = process.cwd()) {
+    const { repoRoot } = await getRepoContext(cwd);
+    const dir = await ensureSubDir(repoRoot, CONNECTOR_ASSETS_DIR);
+    const filePath = path.join(dir, `${source}.json`);
+    await writeJsonFile(filePath, content);
+    return filePath;
+}
+export async function writeConnectorAssetFiles(source, files, cwd = process.cwd()) {
+    const { repoRoot } = await getRepoContext(cwd);
+    const rootDir = await ensureSubDir(repoRoot, CONNECTOR_ASSETS_DIR);
+    const dir = path.join(rootDir, source);
+    await fs.mkdir(dir, { recursive: true });
+    const written = [];
+    for (const file of files) {
+        const filePath = path.join(dir, file.name);
+        await fs.writeFile(filePath, file.content, "utf8");
+        written.push(filePath);
+    }
+    return written;
+}
+export async function getConnectorRuns(cwd = process.cwd()) {
+    const { repoRoot } = await getRepoContext(cwd);
+    return readJsonFile(getConnectorRunsFile(repoRoot), []);
+}
+export async function getTasks(cwd = process.cwd()) {
+    const { repoRoot } = await getRepoContext(cwd);
+    return readJsonFile(getTasksFile(repoRoot), []);
+}
+export async function getTaskById(taskId, cwd = process.cwd()) {
+    const tasks = await getTasks(cwd);
+    return tasks.find((task) => task.id === taskId) ?? null;
+}
+export async function ensureTransportState(cwd = process.cwd()) {
+    const { repoRoot } = await getRepoContext(cwd);
+    await ensureUmDir(repoRoot);
+    const existing = normalizeTransportState(await readJsonFile(getTransportFile(repoRoot), null));
+    if (existing) {
+        await writeJsonFile(getTransportFile(repoRoot), existing);
+        return existing;
+    }
+    const next = {
+        version: 1,
+        status: "idle",
+        activeTaskId: null,
+        queue: [],
+        stats: { queued: 0, running: 0, completed: 0, failed: 0 },
+        subscriptions: ["task:*", "sync:*", "runtime:*", "context-tree:*"],
+        lastPushAt: null,
+        lastPullAt: null,
+        lastRuntimeCheckAt: null,
+        taskKinds: {},
+        updatedAt: new Date().toISOString(),
+        events: [],
+    };
+    await writeJsonFile(getTransportFile(repoRoot), next);
+    return next;
+}
+export async function getTransportState(cwd = process.cwd()) {
+    return ensureTransportState(cwd);
+}
+export async function updateTransportState(updater, cwd = process.cwd()) {
+    const { repoRoot } = await getRepoContext(cwd);
+    const current = normalizeTransportState(await ensureTransportState(cwd));
+    if (!current)
+        throw new Error("Could not initialize repo transport state.");
+    const next = normalizeTransportState(await updater(current));
+    if (!next)
+        throw new Error("Could not update repo transport state.");
+    await writeJsonFile(getTransportFile(repoRoot), next);
+    return next;
+}
+export async function recordTransportEvent(event, cwd = process.cwd()) {
+    return updateTransportState((state) => ({
+        ...state,
+        updatedAt: new Date().toISOString(),
+        events: [
+            {
+                id: randomUUID(),
+                at: new Date().toISOString(),
+                ...event,
+            },
+            ...(state.events ?? []),
+        ].slice(0, 50),
+    }), cwd);
+}
+async function syncTransportFromTasks(cwd = process.cwd(), markers) {
+    const tasks = await getTasks(cwd);
+    return updateTransportState((state) => ({
+        ...state,
+        status: transportStatusFromTasks(tasks),
+        activeTaskId: tasks.find((task) => task.status === "running")?.id ?? null,
+        queue: tasks.slice(0, 25).map((task) => ({
+            id: task.id,
+            kind: task.kind,
+            title: task.title,
+            status: task.status,
+        })),
+        stats: buildTransportStats(tasks),
+        taskKinds: buildTransportTaskKinds(tasks),
+        lastPushAt: markers?.lastPushAt ?? state.lastPushAt,
+        lastPullAt: markers?.lastPullAt ?? state.lastPullAt,
+        lastRuntimeCheckAt: markers?.lastRuntimeCheckAt ?? state.lastRuntimeCheckAt,
+        updatedAt: new Date().toISOString(),
+    }), cwd);
+}
+export async function getContextTreeState(cwd = process.cwd()) {
+    const { repoRoot } = await getRepoContext(cwd);
+    const existing = await readJsonFile(getContextTreeStateFile(repoRoot), null);
+    if (existing)
+        return existing;
+    return rebuildContextTreeState(cwd);
+}
+export async function rebuildContextTreeState(cwd = process.cwd()) {
+    const { repoRoot, state } = await getRepoContext(cwd);
+    await ensureUmDir(repoRoot);
+    const activeProvider = configManager.providers.find((entry) => entry.id === configManager.config?.activeProvider) ?? null;
+    const [pending, pulled, fixes, hubEntries, connectors, connectorRuns, tasks, transport] = await Promise.all([
+        getPendingMemories(cwd),
+        getPulledMemories(cwd),
+        getPulledFixes(cwd),
+        getInstalledHubEntries(cwd),
+        getInstalledConnectors(cwd),
+        getConnectorRuns(cwd),
+        getTasks(cwd),
+        ensureTransportState(cwd),
+    ]);
+    const companyId = state?.companyId ?? "company";
+    const spaceId = state?.projectId ?? "space";
+    const next = {
+        version: 1,
+        repoRoot,
+        umDir: getUmDir(repoRoot),
+        generatedAt: new Date().toISOString(),
+        summaryHandle: `${state?.companyName ?? "Unlinked"} / ${state?.projectName ?? "Unlinked"} has ${pending.length} pending drafts, ${pulled.length} pulled notes, ${fixes.length} fixes, ${tasks.length} tasks, and ${transport.status} transport status.`,
+        stats: {
+            pendingDrafts: pending.length,
+            pulledContext: pulled.length,
+            pulledFixes: fixes.length,
+            hubEntries: hubEntries.length,
+            connectors: connectors.length,
+            connectorRuns: connectorRuns.length,
+            tasks: tasks.length,
+        },
+        runtime: {
+            companyName: state?.companyName ?? null,
+            spaceName: state?.projectName ?? null,
+            provider: activeProvider ? `${activeProvider.name} (${activeProvider.kind})` : null,
+            model: configManager.config?.activeModel ?? null,
+            transportStatus: transport.status,
+            lastPushAt: state?.lastPushAt ?? null,
+            lastPullAt: state?.lastPullAt ?? null,
+        },
+        nodes: [
+            { id: companyId, label: state?.companyName ?? "Unlinked company", kind: "company", parentId: null, detail: state ? "Current Umbrella company link" : "Repo not linked yet" },
+            { id: spaceId, label: state?.projectName ?? "Unlinked space", kind: "space", parentId: companyId, detail: state?.workspaceName ?? null },
+            { id: "repo-root", label: "Repo Root", kind: "folder", parentId: spaceId, detail: repoRoot },
+            { id: "um-dir", label: ".um", kind: "folder", parentId: "repo-root", detail: getUmDir(repoRoot) },
+            { id: "pending", label: "Local Drafts", kind: "collection", parentId: "um-dir", detail: "Repo-local curations waiting to push", count: pending.length },
+            { id: "pulled", label: "Pulled Context", kind: "collection", parentId: "um-dir", detail: "Latest shared server snapshot", count: pulled.length },
+            { id: "fixes", label: "Known Fixes", kind: "collection", parentId: "um-dir", detail: "Pulled fix knowledge", count: fixes.length },
+            { id: "hub", label: "Hub Entries", kind: "collection", parentId: "um-dir", detail: "Installed reusable bundles", count: hubEntries.length },
+            { id: "connectors", label: "Connectors", kind: "collection", parentId: "um-dir", detail: "Installed repo connectors", count: connectors.length },
+            { id: "runs", label: "Connector Runs", kind: "collection", parentId: "um-dir", detail: "Connector execution reports", count: connectorRuns.length },
+            { id: "tasks", label: "Tasks", kind: "collection", parentId: "um-dir", detail: "Local transport-aware task queue", count: tasks.length },
+            {
+                id: "runtime",
+                label: "Runtime",
+                kind: "runtime",
+                parentId: spaceId,
+                detail: `${transport.status} transport | provider ${activeProvider?.name ?? "none"} | model ${configManager.config?.activeModel ?? "none"}`,
+            },
+            {
+                id: "runtime-provider",
+                label: "Provider",
+                kind: "summary",
+                parentId: "runtime",
+                detail: activeProvider ? `${activeProvider.name} (${activeProvider.kind})` : "No active provider",
+            },
+            {
+                id: "runtime-model",
+                label: "Model",
+                kind: "summary",
+                parentId: "runtime",
+                detail: configManager.config?.activeModel ?? "No active model",
+            },
+            {
+                id: "runtime-transport",
+                label: "Transport Queue",
+                kind: "summary",
+                parentId: "runtime",
+                detail: `status=${transport.status} | active=${transport.activeTaskId ?? "none"} | queue=${transport.queue.length}`,
+            },
+            {
+                id: "runtime-transport-events",
+                label: "Transport Events",
+                kind: "summary",
+                parentId: "runtime-transport",
+                detail: `${transport.events.length} retained transport events`,
+                count: transport.events.length,
+            },
+            ...Object.entries(transport.taskKinds ?? {}).map(([kind, count]) => ({
+                id: `runtime-task-kind-${kind}`,
+                label: `Task Kind: ${kind}`,
+                kind: "summary",
+                parentId: "tasks",
+                detail: `${count} recorded ${kind} task${count === 1 ? "" : "s"}`,
+                count,
+            })),
+        ],
+    };
+    await writeJsonFile(getContextTreeStateFile(repoRoot), next);
+    return next;
+}
+export async function createTask(input, cwd = process.cwd()) {
+    const { repoRoot } = await getRepoContext(cwd);
+    await ensureUmDir(repoRoot);
+    const tasks = await readJsonFile(getTasksFile(repoRoot), []);
+    const now = new Date().toISOString();
+    const task = {
+        id: randomUUID(),
+        createdAt: now,
+        updatedAt: now,
+        finishedAt: null,
+        startedAt: input.status === "running" ? now : null,
+        input: input.focus ?? null,
+        result: null,
+        streamingContent: null,
+        reasoningContents: [],
+        toolCalls: [],
+        ...input,
+    };
+    tasks.unshift(task);
+    await writeJsonFile(getTasksFile(repoRoot), tasks.slice(0, 100));
+    await syncTransportFromTasks(cwd);
+    await recordTransportEvent({
+        kind: "task-created",
+        title: task.title,
+        detail: task.detail,
+        status: task.status === "failed" ? "failure" : task.status === "completed" ? "success" : "info",
+        taskId: task.id,
+    }, cwd);
+    if (task.status === "running") {
+        await recordTransportEvent({
+            kind: "task-started",
+            title: task.title,
+            detail: task.detail,
+            status: "info",
+            taskId: task.id,
+        }, cwd);
+    }
+    await rebuildContextTreeState(cwd);
+    return task;
+}
+export async function updateTask(taskId, updater, cwd = process.cwd()) {
+    const { repoRoot } = await getRepoContext(cwd);
+    const tasks = await readJsonFile(getTasksFile(repoRoot), []);
+    const nextTasks = tasks.map((task) => task.id === taskId
+        ? updater({
+            ...task,
+            updatedAt: new Date().toISOString(),
+        })
+        : task);
+    await writeJsonFile(getTasksFile(repoRoot), nextTasks);
+    await syncTransportFromTasks(cwd);
+    await rebuildContextTreeState(cwd);
+    return nextTasks.find((task) => task.id === taskId) ?? null;
+}
+export async function patchTaskLifecycle(taskId, patch, cwd = process.cwd()) {
+    const nextTask = await updateTask(taskId, (task) => ({
+        ...task,
+        status: patch.status,
+        detail: patch.detail ?? task.detail,
+        result: patch.result ?? task.result ?? null,
+        sessionId: patch.sessionId ?? task.sessionId ?? null,
+        startedAt: patch.status === "running" ? task.startedAt ?? new Date().toISOString() : task.startedAt ?? null,
+        streamingContent: patch.streamingContent ?? task.streamingContent ?? null,
+        finishedAt: patch.status === "completed" || patch.status === "failed"
+            ? new Date().toISOString()
+            : task.finishedAt ?? null,
+        updatedAt: new Date().toISOString(),
+    }), cwd);
+    if (!nextTask)
+        return null;
+    const title = nextTask.title;
+    if (patch.status === "running") {
+        await recordTransportEvent({
+            kind: "task-started",
+            title,
+            detail: patch.reason ?? patch.detail ?? nextTask.detail ?? null,
+            status: "info",
+            taskId,
+        }, cwd);
+    }
+    else if (patch.status === "completed") {
+        await recordTransportEvent({
+            kind: "task-completed",
+            title,
+            detail: patch.reason ?? patch.result ?? nextTask.result ?? null,
+            status: "success",
+            taskId,
+        }, cwd);
+    }
+    else if (patch.status === "failed") {
+        await recordTransportEvent({
+            kind: "task-failed",
+            title,
+            detail: patch.reason ?? patch.detail ?? nextTask.detail ?? null,
+            status: "failure",
+            taskId,
+        }, cwd);
+    }
+    return nextTask;
+}
+export async function appendTaskStreamingContent(taskId, content, cwd = process.cwd()) {
+    return updateTask(taskId, (task) => ({
+        ...task,
+        streamingContent: `${task.streamingContent ?? ""}${content}`,
+        updatedAt: new Date().toISOString(),
+    }), cwd);
+}
+export async function addTaskReasoningContent(taskId, content, isThinking = false, cwd = process.cwd()) {
+    return updateTask(taskId, (task) => ({
+        ...task,
+        reasoningContents: [
+            ...(task.reasoningContents ?? []),
+            {
+                content,
+                isThinking,
+                timestamp: new Date().toISOString(),
+            },
+        ],
+        updatedAt: new Date().toISOString(),
+    }), cwd);
+}
+export async function addTaskToolCall(taskId, toolCall, cwd = process.cwd()) {
+    return updateTask(taskId, (task) => ({
+        ...task,
+        toolCalls: [
+            ...(task.toolCalls ?? []),
+            {
+                ...toolCall,
+                timestamp: new Date().toISOString(),
+            },
+        ],
+        updatedAt: new Date().toISOString(),
+    }), cwd);
+}
+export async function completeTask(taskId, status, detail, cwd = process.cwd()) {
+    return patchTaskLifecycle(taskId, {
+        status,
+        detail: detail ?? null,
+        reason: detail ?? null,
+        result: detail ?? null,
+    }, cwd);
+}
+export async function addConnectorRun(input, cwd = process.cwd()) {
+    const { repoRoot } = await getRepoContext(cwd);
+    await ensureUmDir(repoRoot);
+    const runs = await readJsonFile(getConnectorRunsFile(repoRoot), []);
+    const entry = {
+        id: randomUUID(),
+        ranAt: new Date().toISOString(),
+        ...input,
+    };
+    runs.unshift(entry);
+    await writeJsonFile(getConnectorRunsFile(repoRoot), runs.slice(0, 25));
+    await updateRepoContext((state) => ({
+        ...state,
+        updatedAt: new Date().toISOString(),
+    }), cwd);
+    await syncTransportFromTasks(cwd, { lastRuntimeCheckAt: new Date().toISOString() });
+    await recordTransportEvent({
+        kind: "runtime-check",
+        title: `Connector run: ${entry.connectorName}`,
+        detail: entry.summary,
+        status: entry.status === "success" ? "success" : "failure",
+        taskId: null,
+    }, cwd);
+    await rebuildContextTreeState(cwd);
+    return entry;
+}
+export async function writeConnectorRunReport(run, cwd = process.cwd()) {
+    const { repoRoot } = await getRepoContext(cwd);
+    const dir = await ensureSubDir(repoRoot, CONNECTOR_RUN_REPORTS_DIR);
+    const filePath = path.join(dir, `${run.id}.md`);
+    const markdown = [
+        `# ${run.connectorName}`,
+        "",
+        `- Status: ${run.status}`,
+        `- Ran At: ${run.ranAt}`,
+        `- Connector ID: ${run.connectorId}`,
+        "",
+        "## Summary",
+        "",
+        run.summary,
+        "",
+    ].join("\n");
+    await fs.writeFile(filePath, markdown, "utf8");
+    return filePath;
+}
+export async function getSessionState(cwd = process.cwd()) {
+    const { repoRoot } = await getRepoContext(cwd);
+    return normalizeSessionState(await readJsonFile(getSessionFile(repoRoot), null));
+}
+export async function ensureSessionState(cwd = process.cwd()) {
+    const { repoRoot } = await getRepoContext(cwd);
+    await ensureUmDir(repoRoot);
+    const existing = normalizeSessionState(await readJsonFile(getSessionFile(repoRoot), null));
+    if (existing) {
+        await writeJsonFile(getSessionFile(repoRoot), existing);
+        return existing;
+    }
+    const now = new Date().toISOString();
+    const next = {
+        version: 1,
+        id: randomUUID(),
+        startedAt: now,
+        updatedAt: now,
+        commandHistory: [],
+        recentQueries: [],
+        recentCurations: [],
+        lastSummary: null,
+        currentPanel: null,
+        currentFocus: null,
+        panelHistory: [],
+        recentProviderIds: [],
+        recentModels: [],
+        recentHubSlugs: [],
+        recentConnectorSources: [],
+        events: [],
+    };
+    await writeJsonFile(getSessionFile(repoRoot), next);
+    return next;
+}
+export async function resetSessionState(cwd = process.cwd()) {
+    const { repoRoot } = await getRepoContext(cwd);
+    await ensureUmDir(repoRoot);
+    const now = new Date().toISOString();
+    const next = {
+        version: 1,
+        id: randomUUID(),
+        startedAt: now,
+        updatedAt: now,
+        commandHistory: [],
+        recentQueries: [],
+        recentCurations: [],
+        lastSummary: "Started a fresh Context session.",
+        currentPanel: null,
+        currentFocus: null,
+        panelHistory: [],
+        recentProviderIds: [],
+        recentModels: [],
+        recentHubSlugs: [],
+        recentConnectorSources: [],
+        events: [
+            {
+                id: randomUUID(),
+                at: now,
+                kind: "session",
+                title: "Started a fresh Context session",
+                detail: "Local .um data stayed in place, but the live shell history was reset.",
+                panel: "session",
+                focus: null,
+                status: "info",
+            },
+        ],
+    };
+    await writeJsonFile(getSessionFile(repoRoot), next);
+    return next;
+}
+export async function updateSessionState(updater, cwd = process.cwd()) {
+    const { repoRoot } = await getRepoContext(cwd);
+    const current = normalizeSessionState(await ensureSessionState(cwd));
+    if (!current) {
+        throw new Error("Could not initialize repo session state.");
+    }
+    const next = normalizeSessionState(await updater(current));
+    if (!next) {
+        throw new Error("Could not update repo session state.");
+    }
+    await writeJsonFile(getSessionFile(repoRoot), next);
+    return next;
+}
+export async function recordSessionCommand(command, cwd = process.cwd()) {
+    return updateSessionState((state) => ({
+        ...state,
+        updatedAt: new Date().toISOString(),
+        commandHistory: [...(state.commandHistory ?? []), command].slice(-50),
+    }), cwd);
+}
+export async function recordSessionQuery(query, cwd = process.cwd()) {
+    return updateSessionState((state) => ({
+        ...state,
+        updatedAt: new Date().toISOString(),
+        recentQueries: [query, ...(state.recentQueries ?? []).filter((entry) => entry !== query)].slice(0, 10),
+    }), cwd);
+}
+export async function recordSessionCuration(content, cwd = process.cwd()) {
+    return updateSessionState((state) => ({
+        ...state,
+        updatedAt: new Date().toISOString(),
+        recentCurations: [content, ...(state.recentCurations ?? []).filter((entry) => entry !== content)].slice(0, 10),
+    }), cwd);
+}
+export async function setSessionSummary(summary, cwd = process.cwd()) {
+    return updateSessionState((state) => ({
+        ...state,
+        updatedAt: new Date().toISOString(),
+        lastSummary: summary,
+    }), cwd);
+}
+export async function setSessionPanel(panel, focus, cwd = process.cwd()) {
+    return updateSessionState((state) => ({
+        ...state,
+        updatedAt: new Date().toISOString(),
+        currentPanel: panel,
+        currentFocus: focus ?? null,
+        panelHistory: panel
+            ? [panel, ...(state.panelHistory ?? []).filter((entry) => entry !== panel)].slice(0, 10)
+            : (state.panelHistory ?? []),
+    }), cwd);
+}
+export async function recordSessionProvider(providerId, cwd = process.cwd()) {
+    return updateSessionState((state) => ({
+        ...state,
+        updatedAt: new Date().toISOString(),
+        recentProviderIds: [providerId, ...(state.recentProviderIds ?? []).filter((entry) => entry !== providerId)].slice(0, 5),
+    }), cwd);
+}
+export async function recordSessionModel(modelId, cwd = process.cwd()) {
+    return updateSessionState((state) => ({
+        ...state,
+        updatedAt: new Date().toISOString(),
+        recentModels: [modelId, ...(state.recentModels ?? []).filter((entry) => entry !== modelId)].slice(0, 5),
+    }), cwd);
+}
+export async function recordSessionHubEntry(slug, cwd = process.cwd()) {
+    return updateSessionState((state) => ({
+        ...state,
+        updatedAt: new Date().toISOString(),
+        recentHubSlugs: [slug, ...(state.recentHubSlugs ?? []).filter((entry) => entry !== slug)].slice(0, 5),
+    }), cwd);
+}
+export async function recordSessionConnector(source, cwd = process.cwd()) {
+    return updateSessionState((state) => ({
+        ...state,
+        updatedAt: new Date().toISOString(),
+        recentConnectorSources: [source, ...(state.recentConnectorSources ?? []).filter((entry) => entry !== source)].slice(0, 5),
+    }), cwd);
+}
+export async function recordSessionEvent(event, cwd = process.cwd()) {
+    return updateSessionState((state) => ({
+        ...state,
+        updatedAt: new Date().toISOString(),
+        events: [
+            {
+                id: randomUUID(),
+                at: new Date().toISOString(),
+                ...event,
+            },
+            ...(state.events ?? []),
+        ].slice(0, 30),
+    }), cwd);
 }
 export function summarizeLocalMemoryMatches(entries, query) {
     const needle = query.trim().toLowerCase();