@zq-silk/yui 0.6.0 → 0.6.2

package/dist/observability/executionAudit.js

@@ -0,0 +1,545 @@
+/**
+ * Read-only execution audit aggregator (Issue 11 §3).
+ *
+ * The audit answers "what happened in this Home" from durable records alone:
+ * Runs/failures/durations, wake reasons, Session generations, Review execution
+ * vs semantic failures, Integration failure classes and gate reuse, telemetry
+ * volume, and the longest/stale executions. It never writes Task state, never
+ * wakes a Leader, and never takes the storage write lock — it only calls the
+ * store's read methods. A section that cannot be read degrades to an error
+ * entry while the rest of the report stays usable (Issue 11 minimal failure
+ * semantics).
+ */
+import { readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { openCompatibleFileTaskStore } from "../storage/compatibleTaskStore.js";
+import { resolveTaskStoreBackendForHome } from "../storage/sqliteStore.js";
+import { classifyAgentRunFailure, classifyIntegrationAttempt, classifyReviewRound, classifyWakeReasons, countFaultClasses } from "./faultClassification.js";
+import { UNSUPPORTED } from "./runtimeIdentity.js";
+export function createProductionExecutionAuditPorts() {
+    return {
+        openStore: (home) => openCompatibleFileTaskStore(home),
+        directorySize: (path) => directorySizeBytes(path)
+    };
+}
+function directorySizeBytes(path) {
+    // Node has no built-in recursive du; use a bounded iterative walk. The audit
+    // is read-only and a permission/race error degrades to unsupported.
+    try {
+        const root = statSync(path);
+        if (!root.isDirectory())
+            return root.size;
+    }
+    catch {
+        return null;
+    }
+    let total = 0;
+    const stack = [path];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        let entries;
+        try {
+            entries = readdirSync(current, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const child = join(current, entry.name);
+            try {
+                if (entry.isDirectory()) {
+                    stack.push(child);
+                }
+                else if (entry.isFile()) {
+                    total += statSync(child).size;
+                }
+            }
+            catch {
+                // Race with external writers: skip this entry, keep counting.
+            }
+        }
+    }
+    return total;
+}
+const WAKE_REASON_PATTERN = /Yui wakeup reasons: ([^\n.]+)/u;
+function inWindow(createdAt, options) {
+    const time = Date.parse(createdAt);
+    if (!Number.isFinite(time))
+        return true;
+    if (options.since !== undefined && time < options.since.getTime())
+        return false;
+    if (options.until !== undefined && time > options.until.getTime())
+        return false;
+    return true;
+}
+function roleBucket(roleName) {
+    const normalized = roleName.toLowerCase();
+    if (normalized === "leader")
+        return "leader";
+    if (normalized === "reviewer")
+        return "reviewer";
+    if (normalized.startsWith("implementer") || normalized.startsWith("worker")) {
+        return "implementer";
+    }
+    return "other";
+}
+function durationMs(run) {
+    if (run.endedAt === undefined)
+        return 0;
+    return Math.max(0, Date.parse(run.endedAt) - Date.parse(run.createdAt));
+}
+function ok(data) {
+    return { status: "ok", data };
+}
+function failed(error) {
+    return {
+        status: "error",
+        error: error instanceof Error ? error.message : String(error)
+    };
+}
+/**
+ * Run the read-only audit. The store is opened once and only read methods are
+ * called; no transaction, no Event, no Message, no wake is produced.
+ */
+export function runExecutionAudit(home, options = {}, ports = createProductionExecutionAuditPorts()) {
+    const generatedAt = new Date().toISOString();
+    const scope = {
+        ...(options.taskId === undefined ? {} : { taskId: options.taskId }),
+        ...(options.since === undefined ? {} : { since: options.since.toISOString() }),
+        ...(options.until === undefined ? {} : { until: options.until.toISOString() })
+    };
+    let store;
+    try {
+        store = ports.openStore(home);
+    }
+    catch (error) {
+        const section = failed(error);
+        return {
+            generatedAt,
+            home,
+            homeIdentity: UNSUPPORTED,
+            scope,
+            tasks: section,
+            runs: section,
+            wakes: section,
+            sessions: section,
+            reviews: section,
+            integrations: section,
+            events: section,
+            workItems: section,
+            storage: section,
+            topLongRunning: section
+        };
+    }
+    let homeIdentity = UNSUPPORTED;
+    try {
+        homeIdentity = store.getHomeIdentity().homeId;
+    }
+    catch {
+        homeIdentity = UNSUPPORTED;
+    }
+    const taskIds = (() => {
+        try {
+            const tasks = store.listTasks();
+            return tasks
+                .filter((task) => options.taskId === undefined || task.id === options.taskId)
+                .map((task) => task.id);
+        }
+        catch {
+            return [];
+        }
+    })();
+    const tasks = (() => {
+        try {
+            const tasks = store.listTasks().filter((task) => options.taskId === undefined || task.id === options.taskId);
+            return ok({
+                total: tasks.length,
+                archived: tasks.filter((task) => task.status === "archived").length,
+                active: tasks.filter((task) => task.status === "active").length
+            });
+        }
+        catch (error) {
+            return failed(error);
+        }
+    })();
+    const runs = (() => {
+        try {
+            let total = 0;
+            let active = 0;
+            let yielded = 0;
+            let failedCount = 0;
+            let cumulativeDurationMs = 0;
+            let failedDurationMs = 0;
+            const byRole = { leader: 0, reviewer: 0, implementer: 0, other: 0 };
+            const byPurpose = { execution: 0, review: 0 };
+            const failures = [];
+            for (const taskId of taskIds) {
+                for (const run of store.listAgentRuns(taskId)) {
+                    if (!inWindow(run.createdAt, options))
+                        continue;
+                    total += 1;
+                    byRole[roleBucket(run.roleName)] += 1;
+                    if (run.purpose === "review")
+                        byPurpose.review += 1;
+                    else
+                        byPurpose.execution += 1;
+                    const duration = durationMs(run);
+                    if (run.status === "active") {
+                        active += 1;
+                        cumulativeDurationMs += Math.max(0, Date.now() - Date.parse(run.createdAt));
+                    }
+                    else if (run.status === "yielded") {
+                        yielded += 1;
+                        cumulativeDurationMs += duration;
+                    }
+                    else if (run.status === "failed") {
+                        failedCount += 1;
+                        failedDurationMs += duration;
+                        cumulativeDurationMs += duration;
+                        failures.push(classifyAgentRunFailure(run));
+                    }
+                }
+            }
+            return ok({
+                total,
+                active,
+                yielded,
+                failed: failedCount,
+                failureRate: total === 0 ? 0 : failedCount / total,
+                cumulativeDurationMs,
+                failedDurationMs,
+                byRole,
+                byPurpose,
+                faultClasses: countFaultClasses(failures)
+            });
+        }
+        catch (error) {
+            return failed(error);
+        }
+    })();
+    const wakes = (() => {
+        try {
+            let leaderRuns = 0;
+            let withWakeReasons = 0;
+            let orphanWakes = 0;
+            let orphanYieldOnly = 0;
+            const byReason = new Map();
+            for (const taskId of taskIds) {
+                for (const run of store.listAgentRuns(taskId)) {
+                    if (run.roleName !== "leader")
+                        continue;
+                    if (!inWindow(run.createdAt, options))
+                        continue;
+                    leaderRuns += 1;
+                    const match = WAKE_REASON_PATTERN.exec(run.input);
+                    if (match === null)
+                        continue;
+                    withWakeReasons += 1;
+                    const reasons = match[1].split(",").map((value) => value.trim()).filter(Boolean);
+                    for (const reason of reasons) {
+                        byReason.set(reason, (byReason.get(reason) ?? 0) + 1);
+                    }
+                    if (classifyWakeReasons(reasons).faultClass
+                        === "scheduler-duplicate-suppressed-wake") {
+                        orphanWakes += 1;
+                        if (run.status === "yielded")
+                            orphanYieldOnly += 1;
+                    }
+                }
+            }
+            return ok({
+                leaderRuns,
+                withWakeReasons,
+                orphanWakes,
+                orphanYieldOnly,
+                byReason: Object.fromEntries([...byReason.entries()].sort((left, right) => right[1] - left[1])),
+                // The quiescence/suppression counter is owned by the scheduler Issue;
+                // this build has no producer, so report unsupported rather than 0.
+                suppressedWakes: { status: "unsupported" }
+            });
+        }
+        catch (error) {
+            return failed(error);
+        }
+    })();
+    const sessions = (() => {
+        try {
+            let generations = 0;
+            let broken = 0;
+            let stopped = 0;
+            let other = 0;
+            let resets = 0;
+            let lifecycleEvents = 0;
+            let stopFailures = 0;
+            for (const taskId of taskIds) {
+                for (const set of store.listRoleSessionSets(taskId)) {
+                    const history = Array.isArray(set.history) ? set.history : [];
+                    for (const session of [...history, ...Object.values(set.sessions)]) {
+                        generations += 1;
+                        if (session.status === "broken")
+                            broken += 1;
+                        else if (session.status === "stopped")
+                            stopped += 1;
+                        else
+                            other += 1;
+                    }
+                }
+                for (const event of store.listEvents(taskId)) {
+                    if (!inWindow(event.createdAt, options))
+                        continue;
+                    if (event.type === "runtime.role-session-reset")
+                        resets += 1;
+                    else if (event.type === "runtime.provider-session-lifecycle")
+                        lifecycleEvents += 1;
+                    else if (event.type === "runtime.claude-stop-failure")
+                        stopFailures += 1;
+                }
+            }
+            return ok({
+                generations,
+                broken,
+                stopped,
+                other,
+                resets,
+                lifecycleEvents,
+                stopFailures
+            });
+        }
+        catch (error) {
+            return failed(error);
+        }
+    })();
+    const reviews = (() => {
+        try {
+            let total = 0;
+            let completed = 0;
+            let failedCount = 0;
+            let infraFailed = 0;
+            let semanticNegative = 0;
+            const classes = [];
+            for (const taskId of taskIds) {
+                for (const round of store.listReviewRounds(taskId)) {
+                    if (!inWindow(round.createdAt, options))
+                        continue;
+                    total += 1;
+                    if (round.status === "completed")
+                        completed += 1;
+                    else if (round.status === "failed")
+                        failedCount += 1;
+                    const classification = classifyReviewRound(round);
+                    if (classification.faultClass === "review-infra")
+                        infraFailed += 1;
+                    else if (classification.faultClass === "review-semantic-negative") {
+                        semanticNegative += 1;
+                    }
+                    if (classification.faultClass !== "other")
+                        classes.push(classification);
+                }
+            }
+            return ok({
+                total,
+                completed,
+                failed: failedCount,
+                infraFailed,
+                semanticNegative,
+                faultClasses: countFaultClasses(classes)
+            });
+        }
+        catch (error) {
+            return failed(error);
+        }
+    })();
+    const integrations = (() => {
+        try {
+            let total = 0;
+            let committed = 0;
+            let failedCount = 0;
+            let superseded = 0;
+            let environmentFailures = 0;
+            let staleCasFailures = 0;
+            let candidateFailures = 0;
+            let gateReuse = 0;
+            const classes = [];
+            const seenSignatures = new Set();
+            for (const taskId of taskIds) {
+                for (const attempt of store.listIntegrationAttempts(taskId)) {
+                    if (!inWindow(attempt.createdAt, options))
+                        continue;
+                    total += 1;
+                    if (attempt.status === "committed")
+                        committed += 1;
+                    else if (attempt.status === "failed")
+                        failedCount += 1;
+                    else if (attempt.status === "superseded")
+                        superseded += 1;
+                    const classification = classifyIntegrationAttempt(attempt);
+                    if (classification.faultClass === "integration-environment") {
+                        environmentFailures += 1;
+                    }
+                    else if (classification.faultClass === "stale-base-target-cas") {
+                        staleCasFailures += 1;
+                    }
+                    else if (classification.faultClass === "integration-candidate-failure") {
+                        candidateFailures += 1;
+                    }
+                    if (classification.faultClass !== "other")
+                        classes.push(classification);
+                    if (attempt.candidateCommit !== undefined) {
+                        const signature = `${attempt.candidateCommit}|${attempt.checkCommands.join(",")}`;
+                        if (seenSignatures.has(signature))
+                            gateReuse += 1;
+                        else
+                            seenSignatures.add(signature);
+                    }
+                }
+            }
+            return ok({
+                total,
+                committed,
+                failed: failedCount,
+                superseded,
+                environmentFailures,
+                staleCasFailures,
+                candidateFailures,
+                gateReuse,
+                faultClasses: countFaultClasses(classes)
+            });
+        }
+        catch (error) {
+            return failed(error);
+        }
+    })();
+    const events = (() => {
+        try {
+            let total = 0;
+            let progressEvents = 0;
+            let obsoleteEvents = 0;
+            let messages = 0;
+            for (const taskId of taskIds) {
+                for (const event of store.listEvents(taskId)) {
+                    if (!inWindow(event.createdAt, options))
+                        continue;
+                    total += 1;
+                    if (event.type === "runtime.provider-turn-progress")
+                        progressEvents += 1;
+                    else if (event.type === "runtime.event-obsolete")
+                        obsoleteEvents += 1;
+                }
+                messages += store.listMessages(taskId)
+                    .filter((message) => inWindow(message.createdAt, options))
+                    .length;
+            }
+            return ok({
+                total,
+                progressEvents,
+                semanticEvents: total - progressEvents,
+                obsoleteEvents,
+                messages,
+                progressShare: total === 0 ? 0 : progressEvents / total
+            });
+        }
+        catch (error) {
+            return failed(error);
+        }
+    })();
+    const workItems = (() => {
+        try {
+            let total = 0;
+            let completed = 0;
+            let retired = 0;
+            for (const taskId of taskIds) {
+                for (const item of store.listWorkItems(taskId)) {
+                    if (!inWindow(item.createdAt, options))
+                        continue;
+                    total += 1;
+                    if (item.status === "completed")
+                        completed += 1;
+                    else if (item.status === "retired")
+                        retired += 1;
+                }
+            }
+            return ok({ total, completed, retired });
+        }
+        catch (error) {
+            return failed(error);
+        }
+    })();
+    const storage = (() => {
+        try {
+            let stateJsonBytes = UNSUPPORTED;
+            try {
+                stateJsonBytes = statSync(join(home, "state.json")).size;
+            }
+            catch {
+                stateJsonBytes = UNSUPPORTED;
+            }
+            let databaseBytes = UNSUPPORTED;
+            try {
+                databaseBytes = statSync(join(home, "yui.db")).size;
+            }
+            catch {
+                databaseBytes = UNSUPPORTED;
+            }
+            return ok({
+                stateJsonBytes,
+                databaseBytes,
+                // The audit aggregates history; live db integrity is the status
+                // command's job (it runs PRAGMA quick_check). Report presence/size
+                // and the authoritative backend, not a duplicate health probe.
+                databaseHealth: UNSUPPORTED,
+                backend: resolveTaskStoreBackendForHome(home),
+                runtimeDirBytes: ports.directorySize(join(home, "runtime")) ?? UNSUPPORTED,
+                deploymentsBytes: ports.directorySize(join(home, "runtime", "deployments")) ?? UNSUPPORTED
+            });
+        }
+        catch (error) {
+            return failed(error);
+        }
+    })();
+    const topLongRunning = (() => {
+        try {
+            const entries = [];
+            for (const taskId of taskIds) {
+                for (const run of store.listAgentRuns(taskId)) {
+                    if (!inWindow(run.createdAt, options))
+                        continue;
+                    const duration = run.status === "active"
+                        ? Math.max(0, Date.now() - Date.parse(run.createdAt))
+                        : durationMs(run);
+                    if (duration <= 0)
+                        continue;
+                    entries.push({
+                        taskId,
+                        runId: run.id,
+                        roleName: run.roleName,
+                        status: run.status,
+                        durationMs: duration,
+                        startedAt: run.createdAt
+                    });
+                }
+            }
+            return ok(entries
+                .sort((left, right) => right.durationMs - left.durationMs)
+                .slice(0, 10));
+        }
+        catch (error) {
+            return failed(error);
+        }
+    })();
+    return {
+        generatedAt,
+        home,
+        homeIdentity,
+        scope,
+        tasks,
+        runs,
+        wakes,
+        sessions,
+        reviews,
+        integrations,
+        events,
+        workItems,
+        storage,
+        topLongRunning
+    };
+}

package/dist/observability/faultClassification.js

@@ -0,0 +1,160 @@
+export const FAULT_CLASSES = [
+    "provider-transient",
+    "policy-denied",
+    "session-dead",
+    "delivery-yield-uncertain",
+    "storage-backend-lock",
+    "scheduler-duplicate-suppressed-wake",
+    "review-infra",
+    "review-semantic-negative",
+    "integration-environment",
+    "integration-candidate-failure",
+    "stale-base-target-cas",
+    "archive-resource-leak",
+    "other"
+];
+export const NO_FAULT = Object.freeze({
+    faultClass: "other",
+    basis: "none",
+    evidence: ""
+});
+const PROVIDER_TRANSIENT_PATTERN = /\b5\d{2}\b|gateway time|connection lost|server error|overloaded|rate.?limit|ECONNRESET|socket hang up|API Error|nonstream call error|mid-response/iu;
+const POLICY_DENIED_PATTERN = /policy|permission denied|forbidden|not authorized|\b403\b/iu;
+const SESSION_DEAD_PATTERN = /tmux session exited|session cannot be replaced|could not start|pane[^\n]*(dead|exited)|session[^\n]*(dead|exited|broken)|native session|launch reservation/iu;
+const STORAGE_LOCK_PATTERN = /storage lock|database is locked|SQLITE_BUSY|lock timeout|COMMAND_TIMED_OUT|storage conflict|timed out waiting/iu;
+const DELIVERY_UNCERTAIN_PATTERN = /delivery[^\n]*(uncertain|unknown)|yield[^\n]*(uncertain|unknown)|uncertain[^\n]*(yield|delivery)|push[^\n]*uncertain/iu;
+const STALE_BASE_PATTERN = /stale (role|agent|base|target|state)|expected head|base[^\n]*(changed|moved)|conflict|CAS/iu;
+const INTEGRATION_ENVIRONMENT_PATTERN = /tsc: not found|command not found|ENOENT|runner disappeared|runner vanished|dirty target|wrong argument|not a git repository|npm error|node: not found/iu;
+function excerpt(text, max = 160) {
+    const normalized = text.replace(/\s+/g, " ").trim();
+    return normalized.length <= max ? normalized : `${normalized.slice(0, max)}…`;
+}
+/**
+ * Classify a failed AgentRun. A structured hint (from a future capability
+ * provider) always wins; otherwise the summary is matched as historical
+ * import text. Active/yielded runs return {@link NO_FAULT}.
+ */
+export function classifyAgentRunFailure(run, structured) {
+    if (run.status !== "failed")
+        return NO_FAULT;
+    if (structured !== undefined) {
+        return {
+            faultClass: structured.faultClass,
+            basis: "structured",
+            evidence: structured.evidence
+        };
+    }
+    const summary = run.summary ?? "";
+    if (summary.length === 0) {
+        return { faultClass: "other", basis: "text-historical", evidence: "" };
+    }
+    const text = excerpt(summary);
+    if (POLICY_DENIED_PATTERN.test(summary)) {
+        return { faultClass: "policy-denied", basis: "text-historical", evidence: text };
+    }
+    if (PROVIDER_TRANSIENT_PATTERN.test(summary)) {
+        return { faultClass: "provider-transient", basis: "text-historical", evidence: text };
+    }
+    if (STORAGE_LOCK_PATTERN.test(summary)) {
+        return { faultClass: "storage-backend-lock", basis: "text-historical", evidence: text };
+    }
+    if (DELIVERY_UNCERTAIN_PATTERN.test(summary)) {
+        return { faultClass: "delivery-yield-uncertain", basis: "text-historical", evidence: text };
+    }
+    if (STALE_BASE_PATTERN.test(summary)) {
+        return { faultClass: "stale-base-target-cas", basis: "text-historical", evidence: text };
+    }
+    if (SESSION_DEAD_PATTERN.test(summary)) {
+        return { faultClass: "session-dead", basis: "text-historical", evidence: text };
+    }
+    return { faultClass: "other", basis: "text-historical", evidence: text };
+}
+/**
+ * Review execution failure (the Round itself failed to execute/deliver) is
+ * `review-infra`; a completed Round with failed checks is a semantic negative.
+ */
+export function classifyReviewRound(round) {
+    if (round.status === "failed") {
+        return {
+            faultClass: "review-infra",
+            basis: "structured",
+            evidence: "round status=failed"
+        };
+    }
+    if (round.status === "completed" && (round.checks ?? []).some((c) => c.outcome === "failed")) {
+        const failed = (round.checks ?? [])
+            .filter((c) => c.outcome === "failed")
+            .map((c) => c.name)
+            .join(",");
+        return {
+            faultClass: "review-semantic-negative",
+            basis: "structured",
+            evidence: `failed checks: ${failed}`
+        };
+    }
+    return NO_FAULT;
+}
+/**
+ * Integration failure classes: environment/toolchain failure, stale base/CAS
+ * conflict, or candidate failure. Conflict reports are structured; check
+ * details are matched as historical text.
+ */
+export function classifyIntegrationAttempt(attempt) {
+    if (attempt.status !== "failed")
+        return NO_FAULT;
+    if (attempt.conflict !== undefined) {
+        return {
+            faultClass: "stale-base-target-cas",
+            basis: "structured",
+            evidence: excerpt(attempt.conflict.summary)
+        };
+    }
+    const checkText = (attempt.checks ?? [])
+        .map((c) => `${c.name}: ${c.details ?? c.outcome}`)
+        .join("\n");
+    if (INTEGRATION_ENVIRONMENT_PATTERN.test(checkText)) {
+        return {
+            faultClass: "integration-environment",
+            basis: "text-historical",
+            evidence: excerpt(checkText)
+        };
+    }
+    if ((attempt.checks ?? []).some((c) => c.outcome === "failed")) {
+        return {
+            faultClass: "integration-candidate-failure",
+            basis: "structured",
+            evidence: excerpt(checkText)
+        };
+    }
+    return {
+        faultClass: "other",
+        basis: "structured",
+        evidence: "failed without checks or conflict"
+    };
+}
+/**
+ * Wake reason classification. An orphan wake (the scheduler re-woke a Leader
+ * with no new fact) is the duplicate/suppressed-wake class. Quiescence
+ * suppression counters are owned by the scheduler Issue; when absent the
+ * audit reports `unsupported` instead of guessing.
+ */
+export function classifyWakeReasons(reasons) {
+    if (reasons.some((reason) => reason === "task-orphaned")) {
+        return {
+            faultClass: "scheduler-duplicate-suppressed-wake",
+            basis: "structured",
+            evidence: reasons.join(",")
+        };
+    }
+    return NO_FAULT;
+}
+export function emptyFaultClassCounts() {
+    return Object.freeze(Object.fromEntries(FAULT_CLASSES.map((name) => [name, 0])));
+}
+export function countFaultClasses(classifications) {
+    const counts = new Map(FAULT_CLASSES.map((name) => [name, 0]));
+    for (const { faultClass } of classifications) {
+        counts.set(faultClass, (counts.get(faultClass) ?? 0) + 1);
+    }
+    return Object.freeze(Object.fromEntries(counts));
+}