@shawnowen/comet-mcp 2.3.1 → 2.4.1

package/dist/task-thread-aggregator.js

@@ -0,0 +1,480 @@
+/**
+ * Task Thread Aggregator — Phase A
+ *
+ * Reads all 5 local layers (lifecycle JSONL, session manifest, archive store,
+ * snapshots, alert log) and synthesises a CanonicalTaskThread for each known
+ * taskThreadId. Exposes the TaskThreadProvider interface so Phase B can swap
+ * the implementation for an equa-taskthreads core API client without touching
+ * any consumers (FR-040).
+ *
+ * Spec: specs/041-task-thread-sync/spec.md
+ * Plan: specs/041-task-thread-sync/plan.md §Layer Aggregator
+ */
+import { readFile, readdir } from "fs/promises";
+import { existsSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+import { resolveCanonicalStatus, assertValidTransition, InvalidTransitionError, } from "./task-thread-canonical.js";
+import { archiveStore } from "./tab-group-archive.js";
+import { loadBridgeConfig } from "./bridge-config.js";
+// ─── File Paths ───────────────────────────────────────────────────────────────
+const MANIFEST_PATH = join(homedir(), ".claude", "comet-browser", "session-manifest.json");
+const LIFECYCLE_OUTBOX_PATH = join(homedir(), "equabot", "agent-chat", "outbox-comet.jsonl");
+const CC_LIFECYCLE_URL = process.env.COMET_CC_LIFECYCLE_URL || "http://localhost:3001/command-center/api/comet/lifecycle";
+const ORPHAN_THRESHOLD_MS = 120 * 60 * 1000; // 120 minutes
+// ─── Layer Readers (T-004 through T-008) ──────────────────────────────────────
+async function readArchiveLayer() {
+    try {
+        const entries = await archiveStore.loadAll();
+        const map = new Map();
+        for (const e of entries) {
+            map.set(e.taskThreadId, {
+                status: e.status,
+                title: e.title,
+                urls: e.urls,
+                archivedAt: e.archivedAt ?? null,
+                color: e.color,
+            });
+        }
+        return map;
+    }
+    catch {
+        return new Map();
+    }
+}
+async function readManifestLayer() {
+    try {
+        const raw = await readFile(MANIFEST_PATH, "utf-8");
+        const manifest = JSON.parse(raw);
+        const map = new Map();
+        const now = Date.now();
+        for (const entry of manifest.sessions) {
+            if (!entry.taskThreadId)
+                continue;
+            // ManifestEntry has no status field — infer from lastActivity (FR-033)
+            const age = now - entry.lastActivity;
+            const inferredStatus = age > ORPHAN_THRESHOLD_MS ? "orphaned" : "active";
+            map.set(entry.taskThreadId, {
+                status: inferredStatus,
+                agentId: entry.agentId,
+                taskGoal: entry.taskGoal ?? null,
+                createdAt: entry.createdAt,
+                lastActivity: entry.lastActivity,
+                sessionName: entry.sessionName ?? null,
+                sessionKey: entry.sessionKey,
+            });
+        }
+        return map;
+    }
+    catch {
+        return new Map();
+    }
+}
+async function readLifecycleLayer() {
+    const map = new Map();
+    // Parse JSONL outbox — every row with a `lifecycle` field is a lifecycle event
+    try {
+        const raw = await readFile(LIFECYCLE_OUTBOX_PATH, "utf-8");
+        for (const line of raw.split("\n")) {
+            if (!line.trim())
+                continue;
+            try {
+                const row = JSON.parse(line);
+                if (!row.lifecycle)
+                    continue;
+                const threadId = row.thread ?? row.task;
+                if (!threadId)
+                    continue;
+                const existing = map.get(threadId) ?? {
+                    status: row.lifecycle.status ?? "dispatched",
+                    runId: row.lifecycle.runId ?? null,
+                    agentId: row.from ?? null,
+                    events: [],
+                };
+                existing.events.push({
+                    ts: row.ts ?? 0,
+                    msg: row.msg ?? "",
+                    lifecycle: row.lifecycle,
+                });
+                // Latest event wins for status (rows append-only, last = most recent)
+                existing.status = row.lifecycle.status;
+                if (row.lifecycle.runId)
+                    existing.runId = row.lifecycle.runId;
+                map.set(threadId, existing);
+            }
+            catch { /* skip malformed lines */ }
+        }
+    }
+    catch { /* file absent — no lifecycle events */ }
+    // Best-effort: try CC API for live state; on failure, stick with JSONL-derived
+    try {
+        const resp = await fetch(`${CC_LIFECYCLE_URL}?action=list`, {
+            signal: AbortSignal.timeout(3000),
+        });
+        if (resp.ok) {
+            const data = await resp.json();
+            for (const run of data) {
+                if (!run.taskThreadId)
+                    continue;
+                const existing = map.get(run.taskThreadId) ?? { status: run.status, runId: run.runId ?? null, agentId: run.agentId ?? null, events: [] };
+                existing.status = run.status; // live state wins over JSONL for active runs
+                map.set(run.taskThreadId, existing);
+            }
+        }
+    }
+    catch { /* CC offline — JSONL is the fallback */ }
+    return map;
+}
+async function readSnapshotLayer() {
+    const map = new Map();
+    const config = loadBridgeConfig();
+    const snapshotDirs = [
+        config.cleanup.snapshotDir,
+        join(homedir(), "equabot", "orchestration", "task-threads"),
+    ];
+    for (const dir of snapshotDirs) {
+        if (!existsSync(dir))
+            continue;
+        try {
+            const files = await readdir(dir);
+            for (const filename of files.filter((f) => f.endsWith(".json"))) {
+                const file = join(dir, filename);
+                try {
+                    const raw = await readFile(file, "utf-8");
+                    const snap = JSON.parse(raw);
+                    if (!snap.taskThreadId)
+                        continue;
+                    // Keep the most recently captured snapshot per thread
+                    const existing = map.get(snap.taskThreadId);
+                    if (!existing || new Date(snap.capturedAt) > new Date(existing.capturedAt)) {
+                        map.set(snap.taskThreadId, {
+                            taskStatus: snap.taskStatus,
+                            agentId: snap.agentId,
+                            capturedAt: snap.capturedAt,
+                            reason: snap.reason,
+                            tabs: snap.tabs.map((t) => ({ url: t.url, title: t.title })),
+                        });
+                    }
+                }
+                catch { /* skip malformed files */ }
+            }
+        }
+        catch { /* skip unreadable directories */ }
+    }
+    return map;
+}
+async function readAlertLogLayer(manifestMap) {
+    const map = new Map();
+    // Build a reverse index: sessionKey → taskThreadId from manifest
+    const sessionKeyToThread = new Map();
+    for (const [threadId, rec] of manifestMap) {
+        sessionKeyToThread.set(rec.sessionKey, threadId);
+    }
+    try {
+        const config = loadBridgeConfig();
+        const raw = await readFile(config.alerts.logPath, "utf-8");
+        for (const line of raw.split("\n")) {
+            if (!line.trim())
+                continue;
+            try {
+                const event = JSON.parse(line);
+                const threadId = event.sessionKey ? sessionKeyToThread.get(event.sessionKey) : undefined;
+                if (!threadId)
+                    continue;
+                const arr = map.get(threadId) ?? [];
+                arr.push(event);
+                map.set(threadId, arr);
+            }
+            catch { /* skip malformed lines */ }
+        }
+    }
+    catch { /* alert log absent */ }
+    return map;
+}
+// ─── History Timeline Builder (T-009) ─────────────────────────────────────────
+function lifecycleActionToEventType(action) {
+    switch (action) {
+        case "start": return "LifecycleStarted";
+        case "complete": return "LifecycleCompleted";
+        case "abort": return "LifecycleAborted";
+        case "pause": return "LifecyclePaused";
+        case "resume": return "LifecycleResumed";
+        default: return "LifecycleUpdated";
+    }
+}
+function buildHistoryTimeline(threadId, lifecycle, manifest, archive, snapshot, alerts, canonicalStatus) {
+    const events = [];
+    // Lifecycle events
+    if (lifecycle) {
+        for (const le of lifecycle.events) {
+            events.push({
+                id: `lifecycle:${le.lifecycle.runId ?? threadId}:${le.ts}`,
+                timestamp: new Date(le.ts * 1000).toISOString(),
+                type: lifecycleActionToEventType(le.lifecycle.action),
+                layer: "lifecycle",
+                summary: le.msg || `Lifecycle ${le.lifecycle.action}`,
+                payload: { ...le.lifecycle },
+            });
+        }
+    }
+    // Session manifest registration
+    if (manifest) {
+        events.push({
+            id: `manifest:${manifest.sessionKey}:created`,
+            timestamp: new Date(manifest.createdAt).toISOString(),
+            type: "SessionRegistered",
+            layer: "session-manifest",
+            summary: `Session registered — agent=${manifest.agentId}${manifest.taskGoal ? `, goal="${manifest.taskGoal.slice(0, 60)}"` : ""}`,
+            payload: { sessionKey: manifest.sessionKey, agentId: manifest.agentId, status: manifest.status },
+        });
+        if (manifest.status === "orphaned") {
+            events.push({
+                id: `manifest:${manifest.sessionKey}:orphaned`,
+                timestamp: new Date(manifest.lastActivity).toISOString(),
+                type: "OrphanDetected",
+                layer: "session-manifest",
+                summary: "Session went orphaned (agent lost heartbeat)",
+                payload: { sessionKey: manifest.sessionKey, lastActivity: manifest.lastActivity },
+            });
+        }
+    }
+    // Archive events
+    if (archive) {
+        if (archive.archivedAt) {
+            events.push({
+                id: `archive:${threadId}:archived`,
+                timestamp: archive.archivedAt,
+                type: "Archived",
+                layer: "archive",
+                summary: `Tab group archived — "${archive.title}" (${archive.urls.length} tabs)`,
+                payload: { title: archive.title, urls: archive.urls, color: archive.color },
+            });
+        }
+    }
+    // Snapshot events
+    if (snapshot) {
+        events.push({
+            id: `snapshot:${threadId}:${snapshot.capturedAt}`,
+            timestamp: snapshot.capturedAt,
+            type: "SnapshotCaptured",
+            layer: "snapshot",
+            summary: `Snapshot captured — reason=${snapshot.reason}, status=${snapshot.taskStatus}`,
+            payload: { reason: snapshot.reason, taskStatus: snapshot.taskStatus, tabCount: snapshot.tabs.length },
+        });
+    }
+    // Alert log events
+    if (alerts) {
+        for (const alert of alerts) {
+            events.push({
+                id: `alert:${alert.id}`,
+                timestamp: alert.timestamp,
+                type: alert.type === "ORPHAN_DETECTED" || alert.type === "ORPHAN_REAPED"
+                    ? "OrphanDetected"
+                    : "AlertFired",
+                layer: "alert-log",
+                summary: `[${alert.severity}] ${alert.message}`,
+                payload: { alertType: alert.type, severity: alert.severity, context: alert.context },
+            });
+        }
+    }
+    // Sort ascending by timestamp
+    events.sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+    // Mark superseded events (FR-009):
+    // If a lifecycle terminal state exists, any non-lifecycle active-state events are superseded
+    const lifecycleIsTerminal = lifecycle &&
+        (lifecycle.status === "completed" || lifecycle.status === "aborted");
+    if (lifecycleIsTerminal) {
+        for (const ev of events) {
+            if (ev.layer !== "lifecycle") {
+                const activeTypes = ["SessionRegistered", "LifecycleStarted"];
+                if (activeTypes.includes(ev.type)) {
+                    ev.superseded = true;
+                }
+            }
+        }
+    }
+    return events;
+}
+// ─── Thread Assembler (T-010) ─────────────────────────────────────────────────
+function assembleThread(threadId, lifecycle, manifest, archive, snapshot, alerts, stale) {
+    const layerStates = {
+        lifecycle: lifecycle?.status ?? null,
+        snapshot: snapshot?.taskStatus ?? null,
+        sessionManifest: manifest?.status ?? null,
+        archive: archive?.status ?? null,
+        alertLog: alerts && alerts.length > 0 ? alerts[alerts.length - 1].type : null,
+    };
+    const status = resolveCanonicalStatus(layerStates);
+    const history = buildHistoryTimeline(threadId, lifecycle, manifest, archive, snapshot, alerts, status);
+    // Title: prefer archive title, then session name, then taskGoal prefix, then threadId
+    const title = archive?.title ??
+        manifest?.sessionName ??
+        (manifest?.taskGoal ? manifest.taskGoal.slice(0, 60) : null) ??
+        threadId;
+    // createdAt: earliest known event
+    const createdAt = history.length > 0
+        ? history[0].timestamp
+        : manifest
+            ? new Date(manifest.createdAt).toISOString()
+            : new Date().toISOString();
+    // terminalAt: latest event if terminal
+    const terminalAt = status === "Completed" || status === "Aborted" || status === "Archived"
+        ? (history.length > 0 ? history[history.length - 1].timestamp : null)
+        : null;
+    // agentId: from lifecycle, then manifest, then snapshot
+    const agentId = lifecycle?.agentId ??
+        manifest?.agentId ??
+        snapshot?.agentId ??
+        null;
+    // DRI: from bridge config orchestratorAgentId (nullable in Phase A, OQ-3)
+    const config = loadBridgeConfig();
+    const dri = config.roles.orchestratorAgentId ?? null;
+    // tabs: from archive urls (TabGroupArchiveEntry.urls is {url,title}[]) or snapshot tabs
+    const tabs = archive?.urls.map((t) => t.url) ??
+        snapshot?.tabs.map((t) => t.url) ??
+        [];
+    const externalLinks = {
+        drive: null,
+        orgCharter: null,
+        linear: null,
+    };
+    return {
+        taskThreadId: threadId,
+        title,
+        status,
+        agentId,
+        dri,
+        createdAt,
+        terminalAt,
+        taskGoal: manifest?.taskGoal ?? null,
+        tabs,
+        externalLinks,
+        history,
+        stale,
+    };
+}
+// ─── Local Task Thread Aggregator (T-010, T-011) ──────────────────────────────
+export class LocalTaskThreadAggregator {
+    async listAll() {
+        const [archiveMap, manifestMap, lifecycleMap, snapshotMap] = await Promise.allSettled([
+            readArchiveLayer(),
+            readManifestLayer(),
+            readLifecycleLayer(),
+            readSnapshotLayer(),
+        ]);
+        const stale = archiveMap.status === "rejected" ||
+            manifestMap.status === "rejected" ||
+            lifecycleMap.status === "rejected" ||
+            snapshotMap.status === "rejected";
+        const archive = archiveMap.status === "fulfilled" ? archiveMap.value : new Map();
+        const manifest = manifestMap.status === "fulfilled" ? manifestMap.value : new Map();
+        const lifecycle = lifecycleMap.status === "fulfilled" ? lifecycleMap.value : new Map();
+        const snapshot = snapshotMap.status === "fulfilled" ? snapshotMap.value : new Map();
+        const alertMap = await readAlertLogLayer(manifest).catch(() => new Map());
+        // Union of all known thread IDs across all layers (FR-010)
+        const allIds = new Set([
+            ...archive.keys(),
+            ...manifest.keys(),
+            ...lifecycle.keys(),
+            ...snapshot.keys(),
+            ...alertMap.keys(),
+        ]);
+        // Assemble concurrently, bounded to 10 (FR-036)
+        const ids = [...allIds];
+        const results = [];
+        for (let i = 0; i < ids.length; i += 10) {
+            const batch = ids.slice(i, i + 10);
+            const assembled = batch.map((id) => assembleThread(id, lifecycle.get(id), manifest.get(id), archive.get(id), snapshot.get(id), alertMap.get(id), stale));
+            results.push(...assembled);
+        }
+        return results;
+    }
+    async get(id) {
+        const [archiveMap, manifestMap, lifecycleMap, snapshotMap] = await Promise.allSettled([
+            readArchiveLayer(),
+            readManifestLayer(),
+            readLifecycleLayer(),
+            readSnapshotLayer(),
+        ]);
+        const stale = archiveMap.status === "rejected" ||
+            manifestMap.status === "rejected" ||
+            lifecycleMap.status === "rejected" ||
+            snapshotMap.status === "rejected";
+        const archive = archiveMap.status === "fulfilled" ? archiveMap.value.get(id) : undefined;
+        const manifest = manifestMap.status === "fulfilled" ? manifestMap.value.get(id) : undefined;
+        const lifecycle = lifecycleMap.status === "fulfilled" ? lifecycleMap.value.get(id) : undefined;
+        const snapshot = snapshotMap.status === "fulfilled" ? snapshotMap.value.get(id) : undefined;
+        const manifestMap2 = manifestMap.status === "fulfilled" ? manifestMap.value : new Map();
+        const alertMap = await readAlertLogLayer(manifestMap2).catch(() => new Map());
+        const alerts = alertMap.get(id);
+        // If no layer knows about this thread, return null
+        if (!archive && !manifest && !lifecycle && !snapshot && !alerts)
+            return null;
+        return assembleThread(id, lifecycle, manifest, archive, snapshot, alerts, stale);
+    }
+    async executeTransition(id, action, reason) {
+        // Fetch current state first
+        const thread = await this.get(id);
+        if (!thread) {
+            throw new Error(`Task thread "${id}" not found`);
+        }
+        // Validate transition (FR-019)
+        assertValidTransition(thread.status, action);
+        // Map action to lifecycle endpoint call (FR-018)
+        const lifecycleAction = {
+            "Start": "start",
+            "Mark Complete": "complete",
+            "Abort": "abort",
+            "Pause": "pause",
+            "Resume": "resume",
+            "Archive": null, // handled via archive store, not lifecycle
+        }[action];
+        if (lifecycleAction !== null && lifecycleAction !== undefined) {
+            // Call the lifecycle endpoint (best-effort — CC may be offline)
+            try {
+                const payload = { action: lifecycleAction, runId: id };
+                if (reason)
+                    payload.reason = reason;
+                const resp = await fetch(CC_LIFECYCLE_URL, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json" },
+                    body: JSON.stringify(payload),
+                    signal: AbortSignal.timeout(5000),
+                });
+                if (!resp.ok) {
+                    const text = await resp.text();
+                    throw new Error(`Lifecycle endpoint error ${resp.status}: ${text.slice(0, 200)}`);
+                }
+            }
+            catch (err) {
+                if (err instanceof InvalidTransitionError)
+                    throw err;
+                // Partial failure: lifecycle call failed — do not corrupt canonical state (FR-020)
+                throw new Error(`Write failed: lifecycle endpoint unreachable. Canonical state unchanged. (${err instanceof Error ? err.message : err})`);
+            }
+        }
+        if (action === "Archive") {
+            // Archive via archive store — update status to archived
+            const archiveEntry = await archiveStore.load(id);
+            if (archiveEntry) {
+                archiveEntry.status = "archived";
+                archiveEntry.archivedAt = new Date().toISOString();
+                await archiveStore.save(archiveEntry);
+            }
+        }
+        // Derive the expected new status from the valid transitions state machine
+        const statusAfterAction = {
+            "Start": "Running",
+            "Mark Complete": "Completed",
+            "Abort": "Aborted",
+            "Pause": "Paused",
+            "Resume": "Running",
+            "Archive": "Archived",
+        };
+        const newStatus = statusAfterAction[action] ?? thread.status;
+        return { newStatus };
+    }
+}
+// Singleton — Phase B: replace with CoreAPITaskThreadProvider
+export const aggregator = new LocalTaskThreadAggregator();
+//# sourceMappingURL=task-thread-aggregator.js.map

package/dist/task-thread-canonical.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Canonical Task Thread Types & Status Rule Set — Phase A
+ *
+ * AUTHORITATIVE LOCATION (FR-004): This file is the single source of truth
+ * for the Phase A canonical status vocabulary, conflict-resolution precedence,
+ * and valid lifecycle transition rules for the Comet browser surface worktree.
+ *
+ * In Phase B this document MUST link to or be replaced by the canonical rule
+ * from equa-taskthreads spec 003 (core API).
+ *
+ * Spec: specs/041-task-thread-sync/spec.md
+ * Plan: specs/041-task-thread-sync/plan.md §Canonical Status Rule Set
+ */
+/**
+ * The six canonical status values for a task thread.
+ * Provisional in Phase A; to be reconciled with equa-taskthreads spec 003
+ * before or during Phase B.
+ */
+export type CanonicalStatus = "Dispatched" | "Running" | "Paused" | "Completed" | "Aborted" | "Archived";
+/** Terminal statuses — once set by the lifecycle layer, cannot revert (FR-008) */
+export declare const TERMINAL_STATUSES: Set<CanonicalStatus>;
+export declare function isTerminal(status: CanonicalStatus): boolean;
+export type LayerName = "lifecycle" | "session-manifest" | "archive" | "snapshot" | "alert-log";
+export type HistoryEventType = "Dispatched" | "SessionRegistered" | "LifecycleStarted" | "LifecycleCompleted" | "LifecycleAborted" | "LifecyclePaused" | "LifecycleResumed" | "LifecycleUpdated" | "SnapshotCaptured" | "Archived" | "Restored" | "UserAction" | "AlertFired" | "MirrorSync" | "OrphanDetected";
+export interface HistoryEvent {
+    /** Stable unique ID for this event (layer:source-id or generated) */
+    id: string;
+    /** ISO-8601 timestamp */
+    timestamp: string;
+    type: HistoryEventType;
+    layer: LayerName;
+    /** Human-readable summary of the event */
+    summary: string;
+    /** Raw source payload for audit purposes */
+    payload?: Record<string, unknown>;
+    /**
+     * True when a higher-priority layer contradicts this event's state reading.
+     * Superseded events are preserved in the timeline for audit (FR-009).
+     */
+    superseded?: boolean;
+}
+export interface ExternalLinks {
+    /** Google Drive folder URL, or null if not mirrored */
+    drive: string | null;
+    /** Org-Charter task URL, or null if not mirrored */
+    orgCharter: string | null;
+    /** Linear issue URL, or null if not mirrored */
+    linear: string | null;
+}
+/**
+ * The canonical representation of a task thread in the Comet browser surface.
+ * Implements the immutable 4-layer anatomy from equa-taskthreads Constitution Principle I:
+ *   - Task Header: id, title, status, agentId, dri, createdAt, terminalAt
+ *   - Thread Summary: taskGoal
+ *   - Resource Links: tabs, externalLinks
+ *   - Conversation: history
+ */
+export interface CanonicalTaskThread {
+    taskThreadId: string;
+    title: string;
+    status: CanonicalStatus;
+    /** Agent currently or last owning this thread; null after terminal state */
+    agentId: string | null;
+    /** Human DRI — nullable in Phase A until equa-taskthreads spec 003 defines authoritative source */
+    dri: string | null;
+    /** ISO-8601 creation time (earliest event across all layers) */
+    createdAt: string;
+    /** ISO-8601 terminal time; null if not yet terminal */
+    terminalAt: string | null;
+    /** Task goal as described at session registration; null if unknown */
+    taskGoal: string | null;
+    /** Archived tab URLs for this thread */
+    tabs: string[];
+    externalLinks: ExternalLinks;
+    /** Merged history timeline across all layers, sorted ascending by timestamp */
+    history: HistoryEvent[];
+    /**
+     * True when one or more layers could not be read and data may be incomplete.
+     * The extension shows a staleness indicator when this is true (FR-016).
+     */
+    stale: boolean;
+}
+/**
+ * Maps each canonical status to the set of write actions the user may invoke
+ * from that state. The extension renders exactly these buttons (FR-017).
+ *
+ * Action names match the payload `action` field for POST /api/task-threads/:id/transition.
+ */
+export declare const VALID_TRANSITIONS: Readonly<Record<CanonicalStatus, readonly string[]>>;
+export interface LayerStates {
+    /**
+     * Phase A: raw status string from the lifecycle JSONL/CC API.
+     * Expected values: "started" | "dispatched" | "paused" | "completed" | "aborted" | null
+     */
+    lifecycle: string | null;
+    /**
+     * From TaskThreadSnapshot.taskStatus
+     * Expected values: "success" | "failed" | "abandoned" | "in-progress" | null
+     */
+    snapshot: string | null;
+    /**
+     * From ManifestEntry SessionStatus
+     * Expected values: "active" | "disconnecting" | "orphaned" | null
+     */
+    sessionManifest: string | null;
+    /**
+     * From TabGroupArchiveEntry.status
+     * Expected values: "saved" | "archived" | null
+     */
+    archive: string | null;
+    /**
+     * From alert log ErrorEventType for this thread
+     * Expected values: "ORPHAN_DETECTED" | "ORPHAN_REAPED" | other | null
+     */
+    alertLog: string | null;
+}
+/**
+ * Derives exactly one canonical status from the union of underlying layer states.
+ *
+ * Precedence (FR-006, FR-007):
+ *   1. Lifecycle layer (highest authority — Lifecycle wins)
+ *   2. Snapshot layer
+ *   3. Session manifest layer
+ *   4. Archive layer
+ *   5. Alert log layer
+ *   6. Unknown → Archived (safe display fallback)
+ *
+ * Terminal states (Completed, Aborted, Archived) are sticky once set by
+ * the lifecycle layer (FR-008).
+ */
+export declare function resolveCanonicalStatus(layers: LayerStates): CanonicalStatus;
+export declare class InvalidTransitionError extends Error {
+    readonly fromStatus: CanonicalStatus;
+    readonly action: string;
+    constructor(fromStatus: CanonicalStatus, action: string);
+}
+/**
+ * Throws InvalidTransitionError if the action is not valid from the given status.
+ * Does NOT perform the transition — call this before executing any write.
+ */
+export declare function assertValidTransition(status: CanonicalStatus, action: string): void;
+//# sourceMappingURL=task-thread-canonical.d.ts.map