@hecer/yoke 1.13.0 → 1.14.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 1.14.0 — 2026-09-09
+
+### Added
+- Add a local-first workspace control room that ranks registered projects by attention, activity, recorded tokens, reported cost, acceptance, or name, with composable search, status filters, UTC scopes, and restorable view links.
+- Add workspace and project analytics with time buckets, token/call/duration/outcome summaries, provider/model/agent/role/phase/run rankings, usage comparisons, and visible measurement coverage.
+- Add project live operations for task and phase state, worker metadata, bounded event timelines, safe-boundary pause/resume, append-only operator notes, and queued change requests.
+- Add a responsive dashboard shell with dark/light themes, keyboard and reduced-motion support, explicit loading/empty/error/stale states, and readable narrow-screen navigation.
+
+### Changed
+- Base dashboard views on durable local history and versioned events while keeping unknown, partial, corrupt, unavailable, and stale telemetry explicit instead of treating it as zero.
+- Keep dashboard controls on the existing loop/goal runner and lock boundaries; browser requests remain typed, same-origin, loopback-only, and unable to execute arbitrary shell commands.
+
+### Fixed
+- Scope dashboard loop verification to the intended local project and retain focused coverage for dashboard authorization, path safety, partial history, concurrency, navigation, and control behavior.
+- Improve light-theme contrast for the active navigation state and keep long project names inside desktop and mobile navigation areas.
+
+### Migration and validation limits
+- No migration is required. Start the local view with `yoke dashboard --no-register`, then register projects with `yoke projects add <path>` as needed. Existing dashboard settings remain local and authoritative.
+- Validated with the dashboard tests, TypeScript lint/build, canonical manifest validation, release metadata checks, package dry run, and real local browser screenshots at desktop and mobile sizes.
+- Dashboard data is limited to explicitly registered local projects and retained local telemetry. It does not provide remote multi-user access, reconstruct missing history, prove requested models were used, or execute arbitrary browser-supplied commands. Pause/resume operates only at existing safe loop/goal boundaries.
+- This release targets npm package 1.14.0; npm publication is triggered by the matching published GitHub release and verified separately.
+
 ## 1.13.0 — 2026-09-08
 
 ### Added

package/README.md

@@ -1,9 +1,9 @@
 <div align="center">
 
-<h1><img src="https://raw.githubusercontent.com/HECer/yoke/v1.13.0/docs/assets/yoke-logo.png" alt="Yoke" width="100" height="63"></h1>
+<h1><img src="https://raw.githubusercontent.com/HECer/yoke/v1.14.0/docs/assets/yoke-logo.png" alt="Yoke" width="100" height="63"></h1>
 
-<!-- yoke:version:start -->1.13.0<!-- yoke:version:end -->
-<!-- yoke:tests:start -->1231<!-- yoke:tests:end -->
+<!-- yoke:version:start -->1.14.0<!-- yoke:version:end -->
+<!-- yoke:tests:start -->1258<!-- yoke:tests:end -->
 <!-- yoke:skills:start -->34<!-- yoke:skills:end -->
 <!-- yoke:agents:start -->Claude | Codex | Gemini | Qwen | OpenCode | Kilo | Pi<!-- yoke:agents:end -->
 
@@ -17,7 +17,7 @@
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](#-license)
 ![Node](https://img.shields.io/badge/node-%E2%89%A520-339933?logo=node.js&logoColor=white)
 ![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=white)
-![Tests](https://img.shields.io/badge/tests-1231%20defined-blue.svg)
+![Tests](https://img.shields.io/badge/tests-1258%20defined-blue.svg)
 ![Agents](https://img.shields.io/badge/agents-Claude%20%7C%20Codex%20%7C%20Gemini%20%7C%20Qwen%20%7C%20OpenCode%20%7C%20Kilo%20%7C%20Pi-8A2BE2)
 ![Built with TDD](https://img.shields.io/badge/built%20with-TDD%20%2B%20review-ff69b4.svg)
 
@@ -40,11 +40,11 @@ yoke projects add /path/to/backend
 yoke dashboard --no-register
 ```
 
-Open the printed `http://127.0.0.1:...` URL. Each registered project has its own goals, tasks and evidence. The dashboard shows available worker state, per-task duration estimates, planned start offsets, input/output tokens, costs and unknown measurements. You can request a goal pause at a safe boundary.
+Open the printed `http://127.0.0.1:...` URL. Each registered project has its own goals, tasks and evidence. The dashboard is a local control room with an overview/ranking screen, project live view, bounded **History explorer**, and Workspace analytics by UTC time bucket. It shows worker state, agent/provider/model/variant/role/phase metadata when recorded, per-task duration estimates, planned start offsets, input/output tokens, reported costs, outcomes, and explicit unknown or partial measurements. Dark and light themes, keyboard navigation, responsive layouts, and reduced-motion handling are included.
 
-The dashboard includes attention-first project search and filters, restorable view links, and usage comparisons against the preceding period. See [dashboard behavior and measurement limits](docs/DASHBOARD-EVOLUTION.md).
+The dashboard includes attention-first project search and filters, project ranking by attention, last activity, token usage, reported cost, acceptance, or name, restorable view links, and usage comparisons against the preceding period. From a project’s live view you can request a safe-boundary pause or resume, add an operator note, and use **Queue a change** for the next planning boundary. See [dashboard behavior and measurement limits](docs/DASHBOARD-EVOLUTION.md) and the [dashboard overhaul contract](docs/DASHBOARD-OVERHAUL.md).
 
-Projects are registered explicitly; this version does not automatically discover every process or aggregate other computers. Start/resume and budget changes use the CLI. Missing history appears as unknown; time ranges are empirical estimates, not exact deadlines.
+Projects are registered explicitly; this version does not automatically discover every process or aggregate other computers. Dashboard controls call the existing goal/loop pause and resume boundaries and never execute arbitrary shell commands. Change requests are append-only pending inbox entries, not immediate code changes. The server stays loopback-only and POST actions require same-origin session authorization; the local Yoke process remains the authority for execution. Missing history appears as unknown; time ranges are empirical estimates, not exact deadlines. Read the [overhaul contract](docs/DASHBOARD-OVERHAUL.md) for data limits and non-goals.
 
 ### Verified goals and efficient execution
 
@@ -925,7 +925,7 @@ release provenance.
 ## 🧪 Development
 
 ```bash
-npm test          # vitest (1231 tests)
+npm test          # vitest (1258 tests)
 npm run build     # tsc, no emit errors
 npm run yoke -- validate canon
 ```

package/canon/manifest.yaml

@@ -1,5 +1,5 @@
 name: yoke-canon
-version: 1.13.0
+version: 1.14.0
 agents: [claude, codex, gemini, qwen, opencode, kilo, pi]
 skills:
   - { id: tdd, path: skills/tdd, kind: methodology, invocation: auto }

package/dist/dashboard/analytics.js

@@ -1,5 +1,6 @@
 import { readMeasurements } from '../observability/history.js';
-import { readEvents } from '../observability/events.js';
+import { EVENT_CAP, readEvents } from '../observability/events.js';
+import { DASHBOARD_LIMITS } from './contracts.js';
 export function parsePeriod(params, now = Date.now()) {
     const to = params.has('to') ? Date.parse(params.get('to')) : now;
     const from = params.has('from') ? Date.parse(params.get('from')) : to - 30 * 86400000;
@@ -9,7 +10,6 @@ export function parsePeriod(params, now = Date.now()) {
     return { from, to, bucket: bucket };
 }
 const finite = (value) => typeof value === 'number' && Number.isFinite(value) && value >= 0;
-const numeric = (value) => finite(value) ? value : 0;
 const name = (value) => typeof value === 'string' ? value.slice(0, 200) : 'unknown';
 function bucketOf(timestamp, bucket) {
     const date = new Date(timestamp);
@@ -20,12 +20,17 @@ function bucketOf(timestamp, bucket) {
     return date.toISOString().slice(0, 10);
 }
 function empty() {
-    return { inputTokens: 0, outputTokens: 0, cachedInputTokens: 0, cacheWriteInputTokens: 0, reportedCostUsd: 0,
-        measuredCalls: 0, unknownCalls: 0, costReportedCalls: 0, incompleteCosts: 0, callDurationMs: 0, attemptDurationMs: 0,
-        attempts: 0, successfulAttempts: 0, accepted: 0, repairs: 0, escalations: 0, unmeasuredAttempts: 0 };
+    return { inputTokens: null, outputTokens: null, cachedInputTokens: null, cacheWriteInputTokens: null, reasoningOutputTokens: null, reportedCostUsd: null,
+        measuredCalls: 0, unknownCalls: 0, costReportedCalls: 0, incompleteCosts: 0, callDurationMs: null, attemptDurationMs: null,
+        attempts: 0, successfulAttempts: 0, accepted: 0, repairs: 0, escalations: 0, unmeasuredAttempts: 0, activity: 0 };
+}
+function addMetric(target, key, value) {
+    if (finite(value))
+        target[key] = (target[key] ?? 0) + value;
 }
 export function aggregateMeasurements(events, period) {
-    const total = empty(), buckets = new Map(), models = new Map(), modelBuckets = new Map(), tasks = new Map(), phases = new Map();
+    const total = empty(), buckets = new Map(), models = new Map(), modelBuckets = new Map(), tasks = new Map();
+    const dimensions = { agents: new Map(), providers: new Map(), variants: new Map(), roles: new Map(), phases: new Map() };
     const modelDetails = new Map();
     const seen = new Set(), accepted = new Set();
     let earliest, latest;
@@ -42,23 +47,40 @@ export function aggregateMeasurements(events, period) {
             latest = event.timestamp;
         const data = event.data ?? {}, bucket = get(buckets, bucketOf(event.timestamp, period.bucket)), task = get(tasks, event.storyId ?? 'unattributed');
         const targets = [total, bucket, task];
+        for (const target of targets)
+            target.activity++;
         if (event.type === 'tokens') {
             const calls = Array.isArray(data.calls) && data.calls.length ? data.calls : [{ ...data, actualModel: data.model, durationMs: event.durationMs }];
             for (const item of calls) {
                 if (!item || typeof item !== 'object')
                     continue;
                 const call = item;
-                const provider = name(call.provider), model = name(call.actualModel), role = name(call.role);
+                const provider = name(call.provider ?? data.provider), model = name(call.actualModel ?? call.model ?? data.actualModel ?? data.model), role = name(call.role ?? data.role);
                 const key = JSON.stringify([provider, model, role]);
                 modelDetails.set(key, { provider, model, role });
-                for (const target of [...targets, get(models, key), get(modelBuckets, JSON.stringify([bucketOf(event.timestamp, period.bucket), provider, model, role]))]) {
-                    target.inputTokens += numeric(call.inputTokens);
-                    target.outputTokens += numeric(call.outputTokens);
-                    target.cachedInputTokens += numeric(call.cachedInputTokens);
-                    target.cacheWriteInputTokens += numeric(call.cacheWriteInputTokens);
-                    target.reportedCostUsd += numeric(call.totalCostUsd);
-                    target.callDurationMs += numeric(call.durationMs);
-                    const measured = finite(call.inputTokens) && finite(call.outputTokens) && call.usageAvailable !== false && call.measurementComplete !== false;
+                const dimensionTargets = [];
+                for (const [kind, value] of Object.entries({
+                    agents: name(call.agent ?? data.agent ?? data.agentName ?? data.provider),
+                    providers: provider,
+                    variants: name(call.variant ?? data.variant),
+                    roles: role,
+                })) {
+                    const dimension = get(dimensions[kind], value);
+                    dimension.activity++;
+                    dimensionTargets.push(dimension);
+                }
+                for (const target of [...targets, get(models, key), get(modelBuckets, JSON.stringify([bucketOf(event.timestamp, period.bucket), provider, model, role])), ...dimensionTargets]) {
+                    const usageAvailable = call.usageAvailable !== false && data.usageAvailable !== false && call.measurementComplete !== false && data.measurementComplete !== false;
+                    if (usageAvailable) {
+                        addMetric(target, 'inputTokens', call.inputTokens);
+                        addMetric(target, 'outputTokens', call.outputTokens);
+                        addMetric(target, 'cachedInputTokens', call.cachedInputTokens);
+                        addMetric(target, 'cacheWriteInputTokens', call.cacheWriteInputTokens);
+                        addMetric(target, 'reasoningOutputTokens', call.reasoningOutputTokens);
+                    }
+                    addMetric(target, 'reportedCostUsd', call.totalCostUsd);
+                    addMetric(target, 'callDurationMs', call.durationMs);
+                    const measured = finite(call.inputTokens) && finite(call.outputTokens) && usageAvailable;
                     if (measured)
                         target.measuredCalls++;
                     else
@@ -75,7 +97,11 @@ export function aggregateMeasurements(events, period) {
         }
         else if (event.type === 'phase-ended') {
             const phase = name(event.phase);
-            phases.set(phase, (phases.get(phase) ?? 0) + numeric(event.durationMs));
+            const phaseTarget = get(dimensions.phases, phase);
+            phaseTarget.activity++;
+            addMetric(phaseTarget, 'attemptDurationMs', event.durationMs);
+            if (phase === 'repairing')
+                phaseTarget.repairs++;
             if (phase === 'repairing')
                 for (const target of targets)
                     target.repairs++;
@@ -83,7 +109,7 @@ export function aggregateMeasurements(events, period) {
         else if (event.type === 'attempt-ended') {
             for (const target of targets) {
                 target.attempts++;
-                target.attemptDurationMs += numeric(event.durationMs);
+                addMetric(target, 'attemptDurationMs', event.durationMs);
                 if (['completed', 'passed'].includes(event.outcome ?? ''))
                     target.successfulAttempts++;
                 if (data.usageAvailable !== true)
@@ -99,25 +125,163 @@ export function aggregateMeasurements(events, period) {
             }
         }
     }
-    const decorate = (value) => ({ ...value,
-        tokensPerCallMinute: value.callDurationMs > 0 ? (value.inputTokens + value.outputTokens) / (value.callDurationMs / 60000) : null,
-        tokensPerAccepted: value.accepted ? (value.inputTokens + value.outputTokens) / value.accepted : null,
-        timePerAcceptedMs: value.accepted ? value.attemptDurationMs / value.accepted : null,
-        costState: value.costReportedCalls === 0 ? 'unknown' : value.costReportedCalls === value.measuredCalls && value.unknownCalls === 0 && value.unmeasuredAttempts === 0 && value.incompleteCosts === 0 ? 'measured' : 'partial',
-    });
-    return { total: { ...decorate(total), tokensPerElapsedMinute: (total.inputTokens + total.outputTokens) / ((period.to - period.from) / 60000) },
+    const decorate = (value) => {
+        const tokens = value.inputTokens !== null && value.outputTokens !== null ? value.inputTokens + value.outputTokens : null;
+        const costState = value.costReportedCalls === 0 ? 'unknown' : value.costReportedCalls === value.measuredCalls && value.unknownCalls === 0 && value.unmeasuredAttempts === 0 && value.incompleteCosts === 0 ? 'measured' : 'partial';
+        return { ...value,
+            tokensPerCallMinute: tokens !== null && value.callDurationMs !== null && value.callDurationMs > 0 ? tokens / (value.callDurationMs / 60000) : null,
+            tokensPerAccepted: tokens !== null && value.accepted ? tokens / value.accepted : null,
+            timePerAcceptedMs: value.accepted && value.attemptDurationMs !== null ? value.attemptDurationMs / value.accepted : null,
+            costState,
+            attention: value.unknownCalls + value.unmeasuredAttempts + value.incompleteCosts + Math.max(0, value.attempts - value.successfulAttempts) + value.repairs + value.escalations,
+            tokens: { input: value.inputTokens, output: value.outputTokens, cachedInput: value.cachedInputTokens, cacheWriteInput: value.cacheWriteInputTokens, reasoningOutput: value.reasoningOutputTokens, total: tokens },
+            calls: { measured: value.measuredCalls, unknown: value.unknownCalls, total: value.measuredCalls + value.unknownCalls },
+            outcomes: { attempts: value.attempts, successfulAttempts: value.successfulAttempts, accepted: value.accepted, repairs: value.repairs, escalations: value.escalations },
+            time: { callDurationMs: value.callDurationMs, attemptDurationMs: value.attemptDurationMs, elapsedMs: value.attemptDurationMs },
+            cost: { reportedUsd: value.reportedCostUsd, reportedCalls: value.costReportedCalls, incompleteCalls: value.incompleteCosts, state: costState, coverage: costState },
+        };
+    };
+    const dimensionRows = (kind) => [...dimensions[kind]].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([name, value]) => ({ name, ...decorate(value) }));
+    const phaseRows = dimensionRows('phases').map(row => ({ phase: row.name, durationMs: row.time.attemptDurationMs, ...row }));
+    const decoratedTotal = decorate(total);
+    return { total: { ...decoratedTotal, tokensPerElapsedMinute: decoratedTotal.tokensPerCallMinute === null && (total.inputTokens === null || total.outputTokens === null) ? null : (total.inputTokens + total.outputTokens) / ((period.to - period.from) / 60000) },
         buckets: [...buckets].sort(([a], [b]) => a.localeCompare(b)).map(([label, value]) => ({ label, ...decorate(value) })),
         models: [...models].map(([key, value]) => ({ ...modelDetails.get(key), ...decorate(value) })),
         modelBuckets: [...modelBuckets].sort(([a], [b]) => a.localeCompare(b)).map(([key, value]) => { const [label, provider, model, role] = JSON.parse(key); return { label, provider, model, role, ...decorate(value) }; }),
         tasks: [...tasks].map(([storyId, value]) => ({ storyId, ...decorate(value) })),
-        phases: [...phases].map(([phase, durationMs]) => ({ phase, durationMs })), earliest, latest, };
+        phases: phaseRows, earliest, latest,
+        dimensions: { agents: dimensionRows('agents'), providers: dimensionRows('providers'), variants: dimensionRows('variants'), roles: dimensionRows('roles'), phases: phaseRows },
+        agents: dimensionRows('agents'), providers: dimensionRows('providers'), variants: dimensionRows('variants'), roles: dimensionRows('roles'), };
+}
+export function parseRanking(params) {
+    const value = params.get('sort') ?? 'attention';
+    if (!['attention', 'activity', 'tokens', 'cost', 'acceptance', 'name'].includes(value))
+        throw Error('Choose a valid ranking: attention, activity, tokens, cost, acceptance or name');
+    return value;
+}
+function compareNames(left, right) { return left < right ? -1 : left > right ? 1 : 0; }
+function compareMetric(left, right) {
+    if (left === null && right === null)
+        return 0;
+    if (left === null)
+        return 1;
+    if (right === null)
+        return -1;
+    return right - left;
+}
+function rankingComparator(key) {
+    return (left, right) => {
+        if (key === 'name')
+            return compareNames(left.name, right.name) || compareNames(JSON.stringify(left), JSON.stringify(right));
+        return compareMetric(left[key], right[key]) || compareNames(left.name, right.name) || compareNames(JSON.stringify(left), JSON.stringify(right));
+    };
+}
+export function rankProjections(rows) {
+    const views = {};
+    for (const key of ['attention', 'activity', 'tokens', 'cost', 'acceptance', 'name'])
+        views[key] = [...rows].sort(rankingComparator(key));
+    return views;
+}
+function rankingRow(name, value) {
+    return { name, attention: value.attention, activity: value.activity, tokens: value.tokens.total, cost: value.cost.reportedUsd, acceptance: value.outcomes.accepted, costState: value.costState, total: value };
+}
+function dimensionRankings(aggregate, runs = []) {
+    return {
+        agents: rankProjections(aggregate.agents.map(row => rankingRow(row.name, row))),
+        providers: rankProjections(aggregate.providers.map(row => rankingRow(row.name, row))),
+        models: rankProjections(aggregate.models.map(row => rankingRow(row.model, row))),
+        variants: rankProjections(aggregate.variants.map(row => rankingRow(row.name, row))),
+        roles: rankProjections(aggregate.roles.map(row => rankingRow(row.name, row))),
+        phases: rankProjections(aggregate.dimensions.phases.map(row => rankingRow(row.name, row))),
+        runs: rankProjections(runs.map(run => rankingRow(run.runId, run.total))),
+    };
+}
+function projectEvents(root, period) {
+    const history = readMeasurements(root, period.from, period.to), seen = new Set();
+    const events = [...history.events, ...readEvents(root, EVENT_CAP)].filter(event => {
+        const time = Date.parse(event.timestamp);
+        if (seen.has(event.id) || !Number.isFinite(time) || time < period.from || time >= period.to)
+            return false;
+        seen.add(event.id);
+        return true;
+    }).sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+    return { events, errors: history.errors };
+}
+function textValue(value) { return typeof value === 'string' && value.length > 0 ? value.slice(0, 200) : undefined; }
+function eventMetadata(event) {
+    const direct = event, data = event.data ?? {};
+    const calls = Array.isArray(data.calls) ? data.calls.filter(item => item && typeof item === 'object') : [];
+    const sources = [direct, ...calls, data];
+    const first = (keys) => { for (const source of sources)
+        for (const key of keys) {
+            const value = textValue(source[key]);
+            if (value)
+                return value;
+        } return undefined; };
+    return { agent: first(['agent']), provider: first(['provider']), model: first(['actualModel', 'model']), variant: first(['variant']), role: first(['role']) };
+}
+function runProjections(events, period) {
+    const byRun = new Map();
+    for (const event of events)
+        byRun.set(event.runId, [...(byRun.get(event.runId) ?? []), event]);
+    return [...byRun].map(([runId, runEvents]) => {
+        const metadata = {}, phases = [], timestamps = runEvents.map(event => new Date(event.timestamp).toISOString());
+        for (const event of runEvents) {
+            const values = eventMetadata(event);
+            for (const key of ['agent', 'provider', 'model', 'variant', 'role'])
+                if (metadata[key] === undefined && values[key] !== undefined)
+                    metadata[key] = values[key];
+            const phase = textValue(event.phase ?? event.data?.phase);
+            if (phase && !phases.includes(phase))
+                phases.push(phase);
+        }
+        const total = aggregateMeasurements(runEvents, period).total;
+        return { runId, ...metadata, ...(phases.length ? { phase: phases[phases.length - 1], phases } : {}), timestamps, startedAt: timestamps[0], endedAt: timestamps[timestamps.length - 1], events: runEvents, total, analytics: total };
+    }).sort((left, right) => compareNames(left.startedAt, right.startedAt) || compareNames(left.runId, right.runId));
+}
+export function projectHistory(root, period, limit = DASHBOARD_LIMITS.events) {
+    if (!Number.isInteger(limit) || limit < 1 || limit > DASHBOARD_LIMITS.events)
+        throw Error('Limit must be an integer from 1 to ' + DASHBOARD_LIMITS.events);
+    const history = projectEvents(root, period), events = history.events.slice(-limit);
+    return { from: new Date(period.from).toISOString(), to: new Date(period.to).toISOString(), bucket: period.bucket, timezone: 'UTC', events, runs: runProjections(events, period), errors: history.errors,
+        coverage: 'Recorded measurements only. Earlier unrecorded or expired activity cannot be reconstructed. Usage is assigned to its reporting time; durations to their end time.' };
+}
+export function workspaceAnalytics(projects, period, sort = 'attention') {
+    const source = [];
+    const allEvents = [];
+    for (const project of projects.slice(0, DASHBOARD_LIMITS.projects)) {
+        if (project.error || !project.root) {
+            source.push({ project, analytics: null, errors: [project.error ?? 'Project directory is unavailable'] });
+            continue;
+        }
+        try {
+            const history = projectEvents(project.root, period);
+            allEvents.push(...history.events);
+            const aggregate = aggregateMeasurements(history.events, period);
+            source.push({ project, analytics: { ...aggregate, from: new Date(period.from).toISOString(), to: new Date(period.to).toISOString(), bucket: period.bucket, timezone: 'UTC', errors: history.errors, coverage: 'Recorded measurements only. Earlier unrecorded or expired activity cannot be reconstructed. Usage is assigned to its reporting time; durations to their end time.' }, errors: history.errors });
+        }
+        catch (error) {
+            source.push({ project, analytics: null, errors: [error.message] });
+        }
+    }
+    const aggregate = aggregateMeasurements(allEvents, period);
+    const runs = runProjections(allEvents, period);
+    const projectsWithMetrics = source.map(({ project, analytics, errors }) => {
+        const total = analytics?.total;
+        return { id: project.id, name: project.name, analytics, errors, attention: project.attention ?? ((project.error ? 1 : 0) + (total?.attention ?? 0)), activity: total?.activity ?? null, tokens: total?.tokens.total ?? null, cost: total?.cost.reportedUsd ?? null, acceptance: total?.outcomes.accepted ?? null, costState: total?.costState ?? 'unknown' };
+    });
+    const projectRankings = rankProjections(projectsWithMetrics);
+    const rankings = { projects: projectRankings, ...dimensionRankings(aggregate, runs) };
+    return { ...aggregate, from: new Date(period.from).toISOString(), to: new Date(period.to).toISOString(), bucket: period.bucket, timezone: 'UTC',
+        projects: projectRankings[sort], runs, rankings, errors: source.flatMap(row => row.errors) };
 }
 export function projectAnalytics(root, period) {
-    const history = readMeasurements(root, period.from, period.to);
-    const recent = readEvents(root, 1000);
-    return { ...aggregateMeasurements([...history.events, ...recent], period),
+    const history = projectEvents(root, period);
+    const aggregate = aggregateMeasurements(history.events, period);
+    const runs = runProjections(history.events, period);
+    return { ...aggregate,
         from: new Date(period.from).toISOString(), to: new Date(period.to).toISOString(), bucket: period.bucket, timezone: 'UTC',
-        errors: history.errors,
+        runs, rankings: dimensionRankings(aggregate, runs), errors: history.errors,
         coverage: 'Recorded measurements only. Earlier unrecorded or expired activity cannot be reconstructed. Usage is assigned to its reporting time; durations to their end time.',
     };
 }

package/dist/dashboard/contracts.js

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+export const DASHBOARD_LIMITS = {
+    projects: 500,
+    events: 100,
+    historyBytes: 32 * 1024 * 1024,
+    requestBytes: 16 * 1024,
+    fileBytes: 1_048_576,
+    noteChars: 4000,
+    changeChars: 8000,
+};
+export const DashboardControlPayloadSchema = z.object({ action: z.literal('pause') }).strict();
+export const DashboardResumePayloadSchema = z.object({ action: z.literal('resume') }).strict();
+export const DashboardNotePayloadSchema = z.object({ note: z.string().trim().min(1).max(DASHBOARD_LIMITS.noteChars) }).strict();
+export const DashboardChangePayloadSchema = z.object({ request: z.string().trim().min(1).max(DASHBOARD_LIMITS.changeChars) }).strict();
+export const DashboardControlResponseSchema = z.object({ status: z.literal('pause-requested') });
+export function parseDashboardLimit(value) {
+    if (value === null)
+        return DASHBOARD_LIMITS.events;
+    const limit = Number(value);
+    if (!Number.isInteger(limit) || limit < 1 || limit > DASHBOARD_LIMITS.events)
+        throw Error(`Limit must be an integer from 1 to ${DASHBOARD_LIMITS.events}`);
+    return limit;
+}