@multileaf/ai-workflow 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -4,6 +4,21 @@ All notable changes to this project are documented in this file. The format foll
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-10-21
+
+## [0.8.0] - 2026-10-20
+
+### Added
+
+- Standing-context benchmark: `aiw context-bench` measures the persistent context AI Workflow renders into every agent session (root context file, neutral resources under `.aiw/resources/`, `.aiw/context/` layers) per category, offline and deterministically. Byte and file counts are measured; tokens are estimated (characters/4) and labeled as such; a content hash pins the fixture and the report contains no timestamps. `--save` records a checkpoint under `.aiw/checkpoints/` and `--baseline=<path>` exits nonzero on any token regression, giving context changes a cost gate.
+- Task parity suite: `aiw parity [--tasks=directory]` runs YAML parity tasks (`.aiw/parity/` by default) that pin quality constraints on context assembly. Each task compares the full composed context against the just-in-time task-retrieval assembler and fails, naming the exact fact, when a critical fact or completion marker does not survive retrieval. Exit nonzero on any failure makes it a CI gate for context changes; estimated token cost is reported but never gates here. Inter-stage tasks load real artifacts via `sources` (project-relative paths into any layer) and enforce `required_patterns` — every extracted identifier (e.g. `REQ-\d+` from the approved specification) must survive assembly, guarding the identifiers traceability links depend on.
+- Usage sidecar: `aiw usage-sidecar record/report` maintains a versioned ledger at `.aiw/checkpoints/usage-sidecar.yml` with per-run tokens split into billing tiers (cache-read, fresh-input, cache-write, output), a `measured`/`estimated` label that propagates pessimistically to aggregates, and attribution by model and harness (with version). The report exposes `cache_hit_rate` (cache-read over billable input); dollar conversion is intentionally left out. `aiw scan` auto-records interpreter and embedding usage into the ledger with their real measurement label.
+- Cost attribution: `aiw cost-report` joins the usage sidecar with the traceability graph (`aiw trace`) to report tokens per verified requirement — the outcome-denominated cost metric — with attributed and unattributed tokens shown side by side. Sidecar entries accept `--requirement=REQ-###`, and `parseTraceabilityGraph` round-trips the serialized graph.
+- Model routing table: `aiw routing init|show|resolve --category=name` maintains a static, evidence-linked table at `.aiw/routing.yml`. Rules map task categories to models deterministically; each rule names its evidence, and the resolver reports its advisory level (`evidenced`, `unevidenced-rule`, `default-fallback`, `default-unset`). Routing is advisory only and never invokes a model.
+- Task-lifecycle token usage: `aiw task-usage [--workflow=id-or-ticket]` aggregates sidecar entries correlated by `--workflow` into one task's totals — input tokens (all billing tiers), output tokens, cache hit rate, per-stage breakdown with models, requirements touched, and harness attribution. Tokens are the model-invariant metric, so lifecycle totals stay comparable across model routing changes; `usage-sidecar record` accepts `--workflow` for correlation.
+- Harness log import: `aiw usage-sidecar import --from=claude-code|codex|gemini|pi` turns local harness session logs into measured ledger entries with all billing tiers, model, and harness attribution. Claude Code imports deduplicate stream chunks by message id; Codex sessions are scoped to the project via `session_meta.cwd` with cached input separated from fresh; Gemini planner responses are imported without project scoping (transcripts record no working directory); Pi imports per-message usage with provider attribution and dedicated usage entries (for example cache warming), scoped by project directory. Import is idempotent via stable per-event identities, so reruns never double-count. Sidecar entries and reports now attribute tokens by provider alongside model and harness, and the docs ship a harness support matrix declaring per-harness capabilities (with Pi recommended as the fullest experience).
+- Session heartbeat: `aiw heartbeat` records beats from harness hooks (`aiw hooks install --target=claude-code` wires Stop and UserPromptSubmit) and decides by idle gap — inside the warn window (default 4 min) it saves a compact checkpoint while the provider cache is still warm; past the TTL it saves one so the next gap resumes cheap. No timers or keep-alive pings: the gap is measured on the next beat, guaranteeing a session never pays the full-price prefix rebuild twice in a row. Thresholds are configurable, state lives in `.aiw/heartbeats.yml`, and hook installation is project-scoped, merge-safe, and idempotent.
+
 ## [0.7.0] - 2026-10-13
 
 ### Added

package/dist/context-benchmark.d.ts

@@ -0,0 +1,52 @@
+import type { FileSystem } from "./types.js";
+/**
+ * Standing-context benchmark (deterministic, offline, zero API cost).
+ *
+ * Measures the persistent context AI Workflow renders into every agent
+ * session: the root context file for the active target, neutral resources
+ * under `.aiw/resources/`, and composed context layers under `.aiw/context/`.
+ *
+ * Honest-measurement rules (see docs/token-efficiency-study-notes.md):
+ * - byte and file counts are `measured`; token counts are `estimated`
+ *   (characters/4) and always labeled as such;
+ * - the bundle hash pins the exact fixture content behind every number;
+ * - output contains no timestamps or randomness, so reruns are
+ *   byte-identical for unchanged projects.
+ */
+export declare const CONTEXT_BENCH_SCHEMA = 1;
+export declare const ROOT_CONTEXT_FILES: readonly ["AGENTS.md", "CLAUDE.md", "GEMINI.md"];
+export declare const RESOURCE_CATEGORIES: readonly ["skills", "rules", "agents", "hooks", "templates"];
+export type ResourceCategory = (typeof RESOURCE_CATEGORIES)[number];
+export type ContextBenchCategory = ResourceCategory | "root-context" | "context-layers" | "other-resources";
+export declare const CONTEXT_BENCH_CATEGORIES: readonly ContextBenchCategory[];
+export type ContextBenchCategoryMetrics = {
+    name: ContextBenchCategory;
+    files: number;
+    characters: number;
+    estimatedTokens: number;
+    paths: string[];
+};
+export type ContextBenchReport = {
+    schema: number;
+    bundleHash: string;
+    totalCharacters: number;
+    totalEstimatedTokens: number;
+    categories: ContextBenchCategoryMetrics[];
+};
+/** Estimate tokens from characters. Always labeled `estimated`, never `measured`. */
+export declare function estimateTokens(text: string): number;
+/** Collect the standing-context report for a project. Deterministic: same files, same bytes, same report. */
+export declare function collectContextBench(root: string, fs: FileSystem): ContextBenchReport;
+export declare function serializeContextBench(report: ContextBenchReport): string;
+/** Parse a previously saved report for baseline comparison. */
+export declare function parseContextBench(content: string): ContextBenchReport;
+export type ContextBenchComparison = {
+    bundleChanged: boolean;
+    totalTokenDelta: number;
+    regressions: string[];
+};
+/**
+ * Compare a current report against a saved baseline.
+ * Follows the parity-harness rule: any token increase is a regression.
+ */
+export declare function compareContextBench(baseline: ContextBenchReport, current: ContextBenchReport): ContextBenchComparison;

package/dist/context-benchmark.js

@@ -0,0 +1,170 @@
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+/**
+ * Standing-context benchmark (deterministic, offline, zero API cost).
+ *
+ * Measures the persistent context AI Workflow renders into every agent
+ * session: the root context file for the active target, neutral resources
+ * under `.aiw/resources/`, and composed context layers under `.aiw/context/`.
+ *
+ * Honest-measurement rules (see docs/token-efficiency-study-notes.md):
+ * - byte and file counts are `measured`; token counts are `estimated`
+ *   (characters/4) and always labeled as such;
+ * - the bundle hash pins the exact fixture content behind every number;
+ * - output contains no timestamps or randomness, so reruns are
+ *   byte-identical for unchanged projects.
+ */
+export const CONTEXT_BENCH_SCHEMA = 1;
+export const ROOT_CONTEXT_FILES = ["AGENTS.md", "CLAUDE.md", "GEMINI.md"];
+export const RESOURCE_CATEGORIES = ["skills", "rules", "agents", "hooks", "templates"];
+export const CONTEXT_BENCH_CATEGORIES = [
+    "root-context",
+    ...RESOURCE_CATEGORIES,
+    "context-layers",
+    "other-resources",
+];
+/** Estimate tokens from characters. Always labeled `estimated`, never `measured`. */
+export function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+function hashBundle(entries) {
+    const hash = createHash("sha256");
+    for (const entry of entries.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0)))
+        hash.update(`${entry.path}\0${Buffer.byteLength(entry.content, "utf8")}\0`);
+    return hash.digest("hex").slice(0, 16);
+}
+function emptyCategory(name) {
+    return { name, files: 0, characters: 0, estimatedTokens: 0, paths: [] };
+}
+function addFile(categories, name, path, content) {
+    const category = categories.get(name) ?? emptyCategory(name);
+    category.files += 1;
+    category.characters += content.length;
+    category.estimatedTokens += estimateTokens(content);
+    category.paths.push(path);
+    categories.set(name, category);
+}
+/** Collect the standing-context report for a project. Deterministic: same files, same bytes, same report. */
+export function collectContextBench(root, fs) {
+    const categories = new Map();
+    const bundle = [];
+    const record = (name, path, content) => {
+        addFile(categories, name, path, content);
+        bundle.push({ path, content });
+    };
+    for (const file of ROOT_CONTEXT_FILES) {
+        const path = join(root, file);
+        if (fs.pathType?.(path) === "file")
+            record("root-context", file, fs.read(path));
+    }
+    const resourceRoot = join(root, ".aiw/resources");
+    if (fs.pathType?.(resourceRoot) === "directory" && fs.listFiles) {
+        for (const relative of fs.listFiles(resourceRoot)) {
+            const absolute = join(resourceRoot, relative);
+            if (fs.pathType?.(absolute) !== "file")
+                continue;
+            const top = relative.split(/[\\/]/)[0];
+            const name = RESOURCE_CATEGORIES.includes(top)
+                ? top
+                : "other-resources";
+            record(name, `.aiw/resources/${relative.split("\\").join("/")}`, fs.read(absolute));
+        }
+    }
+    const contextRoot = join(root, ".aiw/context");
+    if (fs.pathType?.(contextRoot) === "directory") {
+        for (const file of (fs.list?.(contextRoot) ?? [])
+            .filter((name) => name.endsWith(".md"))
+            .sort()) {
+            const absolute = join(contextRoot, file);
+            if (fs.pathType?.(absolute) !== "file")
+                continue;
+            record("context-layers", `.aiw/context/${file}`, fs.read(absolute));
+        }
+    }
+    const ordered = CONTEXT_BENCH_CATEGORIES.map((name) => categories.get(name) ?? emptyCategory(name));
+    return {
+        schema: CONTEXT_BENCH_SCHEMA,
+        bundleHash: hashBundle(bundle),
+        totalCharacters: ordered.reduce((total, category) => total + category.characters, 0),
+        totalEstimatedTokens: ordered.reduce((total, category) => total + category.estimatedTokens, 0),
+        categories: ordered,
+    };
+}
+export function serializeContextBench(report) {
+    const lines = [
+        `schema: ${report.schema}`,
+        `bundle_hash: ${report.bundleHash}`,
+        `total_characters: ${report.totalCharacters}`,
+        `total_estimated_tokens: ${report.totalEstimatedTokens}`,
+        "token_estimate: characters/4 (estimated; byte counts are measured)",
+        "categories:",
+    ];
+    for (const category of report.categories) {
+        lines.push(`  - name: ${category.name}`, `    files: ${category.files}`, `    characters: ${category.characters}`, `    estimated_tokens: ${category.estimatedTokens}`);
+        if (category.paths.length) {
+            lines.push("    paths:");
+            lines.push(...category.paths.map((path) => `      - ${path}`));
+        }
+    }
+    return lines.join("\n") + "\n";
+}
+/** Parse a previously saved report for baseline comparison. */
+export function parseContextBench(content) {
+    const lines = content.split("\n");
+    if (lines[0]?.trim() !== `schema: ${CONTEXT_BENCH_SCHEMA}`)
+        throw new Error("Unrecognized context benchmark report schema.");
+    const report = {
+        schema: CONTEXT_BENCH_SCHEMA,
+        bundleHash: requiredValue(lines, "bundle_hash"),
+        totalCharacters: Number(requiredValue(lines, "total_characters")),
+        totalEstimatedTokens: Number(requiredValue(lines, "total_estimated_tokens")),
+        categories: [],
+    };
+    let current;
+    for (const line of lines.slice(1)) {
+        const category = line.match(/^ {2}- name: (.+)$/);
+        if (category) {
+            current = emptyCategory(category[1]);
+            report.categories.push(current);
+            continue;
+        }
+        const path = line.match(/^ {6}- (.+)$/);
+        if (path && current)
+            current.paths.push(path[1]);
+        const match = line.match(/^ {4}(files|characters|estimated_tokens): (\d+)$/);
+        if (match && current) {
+            const key = match[1] === "estimated_tokens" ? "estimatedTokens" : match[1];
+            current[key] = Number(match[2]);
+        }
+    }
+    if (!report.categories.length)
+        throw new Error("Context benchmark report has no categories.");
+    return report;
+}
+function requiredValue(lines, key) {
+    const value = lines.find((line) => line.startsWith(`${key}: `))?.slice(key.length + 2);
+    if (!value)
+        throw new Error(`Context benchmark report is missing ${key}.`);
+    return value;
+}
+/**
+ * Compare a current report against a saved baseline.
+ * Follows the parity-harness rule: any token increase is a regression.
+ */
+export function compareContextBench(baseline, current) {
+    const baselineByCategory = new Map(baseline.categories.map((category) => [category.name, category]));
+    const regressions = [];
+    for (const category of current.categories) {
+        const previous = baselineByCategory.get(category.name);
+        if (previous && category.estimatedTokens > previous.estimatedTokens)
+            regressions.push(`${category.name}: ${previous.estimatedTokens} -> ${category.estimatedTokens} estimated tokens`);
+    }
+    const totalTokenDelta = current.totalEstimatedTokens - baseline.totalEstimatedTokens;
+    if (totalTokenDelta > 0)
+        regressions.push(`total: ${baseline.totalEstimatedTokens} -> ${current.totalEstimatedTokens} estimated tokens`);
+    return {
+        bundleChanged: baseline.bundleHash !== current.bundleHash,
+        totalTokenDelta,
+        regressions,
+    };
+}

package/dist/cost-attribution.d.ts

@@ -0,0 +1,65 @@
+import { type UsageLabel, type UsageSidecarEntry } from "./usage-sidecar.js";
+import type { TraceabilityGraph } from "./traceability.js";
+/**
+ * Cost attribution per verified requirement — the outcome-denominated cost
+ * metric (Uber's "cost per merged PR", adapted to AI Workflow's unit of
+ * value: a requirement with verification evidence).
+ *
+ * Honesty rules:
+ * - tokens attributed to requirements and unattributed tokens are reported
+ *   side by side, so the ratio cannot be gamed by leaving expensive work
+ *   unattributed;
+ * - the denominator counts only requirements the traceability graph marks
+ *   as verified (linked evidence present);
+ * - labels propagate pessimistically (any estimated entry poisons the total).
+ */
+export type RequirementCost = {
+    requirement: string;
+    tokens: number;
+    label: UsageLabel;
+    verified: boolean;
+};
+export type CostAttribution = {
+    attributed: RequirementCost[];
+    unattributedTokens: number;
+    unattributedLabel: UsageLabel;
+    verifiedRequirements: number;
+    unverifiedRequirements: number;
+    totalTokens: number;
+    totalLabel: UsageLabel;
+    /** Outcome-denominated metric: attributed tokens per verified requirement. */
+    tokensPerVerifiedRequirement?: number;
+};
+export declare function computeCostAttribution(entries: UsageSidecarEntry[], graph: TraceabilityGraph): CostAttribution;
+export declare function serializeCostAttribution(attribution: CostAttribution): string;
+/**
+ * Task-lifecycle usage: total tokens from task start to merged PR.
+ *
+ * Tokens — not dollars — are the model-invariant metric: switching between a
+ * frontier and an entry-level model changes the price per token but not the
+ * input/output consumption, so lifecycle token totals stay comparable across
+ * model routing changes and harness migrations. All input tiers count as
+ * input tokens processed (cached reads still consume tokens; they just bill
+ * less), and the tier split stays visible for cache-behavior analysis.
+ */
+export type TaskUsageStage = {
+    stage: string;
+    tokens: number;
+    label: UsageLabel;
+    models: string[];
+};
+export type TaskUsageSummary = {
+    workflow: string;
+    entries: number;
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    label: UsageLabel;
+    cacheHitRate?: number;
+    stages: TaskUsageStage[];
+    requirements: string[];
+    models: string[];
+    harnesses: string[];
+};
+export declare function summarizeTaskUsage(entries: UsageSidecarEntry[], workflow: string): TaskUsageSummary;
+export declare function serializeTaskUsage(summary: TaskUsageSummary): string;

package/dist/cost-attribution.js

@@ -0,0 +1,119 @@
+import { USAGE_TIERS } from "./usage-sidecar.js";
+const totalTokens = (entry) => USAGE_TIERS.reduce((total, tier) => total + entry.tiers[tier], 0);
+export function computeCostAttribution(entries, graph) {
+    const verifiedByRequirement = new Map(graph.links.map((link) => [link.requirement, link.evidence.length > 0]));
+    const byRequirement = new Map();
+    const unattributed = [];
+    for (const entry of entries) {
+        if (entry.requirement) {
+            const bucket = byRequirement.get(entry.requirement) ?? [];
+            bucket.push(entry);
+            byRequirement.set(entry.requirement, bucket);
+        }
+        else
+            unattributed.push(entry);
+    }
+    const labelOf = (group) => group.every((entry) => entry.label === "measured") ? "measured" : "estimated";
+    const attributed = [...byRequirement]
+        .map(([requirement, group]) => ({
+        requirement,
+        tokens: group.reduce((total, entry) => total + totalTokens(entry), 0),
+        label: labelOf(group),
+        verified: verifiedByRequirement.get(requirement) ?? false,
+    }))
+        .sort((a, b) => b.tokens - a.tokens || a.requirement.localeCompare(b.requirement));
+    const graphRequirements = new Set(graph.links.map((link) => link.requirement));
+    const verifiedRequirements = attributed.filter(({ verified }) => verified).length;
+    const unverifiedRequirements = attributed.filter(({ requirement }) => graphRequirements.has(requirement)).length -
+        verifiedRequirements;
+    const attributedToVerified = attributed
+        .filter(({ verified }) => verified)
+        .reduce((total, entry) => total + entry.tokens, 0);
+    return {
+        attributed,
+        unattributedTokens: unattributed.reduce((total, entry) => total + totalTokens(entry), 0),
+        unattributedLabel: labelOf(unattributed),
+        verifiedRequirements,
+        unverifiedRequirements,
+        totalTokens: entries.reduce((total, entry) => total + totalTokens(entry), 0),
+        totalLabel: labelOf(entries),
+        ...(verifiedRequirements > 0
+            ? { tokensPerVerifiedRequirement: Math.ceil(attributedToVerified / verifiedRequirements) }
+            : {}),
+    };
+}
+export function serializeCostAttribution(attribution) {
+    if (!attribution.attributed.length && !attribution.unattributedTokens)
+        return "No usage recorded against requirements yet. Record with `aiw usage-sidecar record --requirement=REQ-###`.";
+    const lines = [
+        `total_tokens: ${attribution.totalTokens.toLocaleString("en-US")} (${attribution.totalLabel})`,
+        `unattributed_tokens: ${attribution.unattributedTokens.toLocaleString("en-US")} (${attribution.unattributedLabel})`,
+        `verified_requirements: ${attribution.verifiedRequirements}`,
+        `unverified_requirements: ${attribution.unverifiedRequirements}`,
+        ...(attribution.tokensPerVerifiedRequirement === undefined
+            ? ["tokens_per_verified_requirement: n/a (no verified requirements yet)"]
+            : [
+                `tokens_per_verified_requirement: ${attribution.tokensPerVerifiedRequirement.toLocaleString("en-US")} (estimated; outcome-denominated)`,
+            ]),
+        "by requirement:",
+        ...attribution.attributed.map(({ requirement, tokens, label, verified }) => `  - ${requirement}: ${tokens.toLocaleString("en-US")} tokens (${label}, ${verified ? "verified" : "unverified"})`),
+    ];
+    return lines.join("\n");
+}
+export function summarizeTaskUsage(entries, workflow) {
+    const scoped = entries.filter((entry) => entry.workflow === workflow);
+    const labelOf = (group) => group.every((entry) => entry.label === "measured") ? "measured" : "estimated";
+    const inputTokens = scoped.reduce((total, entry) => total + entry.tiers["cache-read"] + entry.tiers["fresh-input"] + entry.tiers["cache-write"], 0);
+    const billableInput = scoped.reduce((total, entry) => total + entry.tiers["cache-read"] + entry.tiers["fresh-input"], 0);
+    const byCommand = new Map();
+    for (const entry of scoped) {
+        const bucket = byCommand.get(entry.command) ?? [];
+        bucket.push(entry);
+        byCommand.set(entry.command, bucket);
+    }
+    const stages = [...byCommand]
+        .map(([stage, group]) => ({
+        stage,
+        tokens: group.reduce((total, entry) => total + totalTokens(entry), 0),
+        label: labelOf(group),
+        models: [...new Set(group.map((entry) => entry.model ?? "unattributed"))].sort(),
+    }))
+        .sort((a, b) => b.tokens - a.tokens || a.stage.localeCompare(b.stage));
+    const uniqueSorted = (values) => [...new Set(values.filter((value) => value !== undefined))].sort();
+    return {
+        workflow,
+        entries: scoped.length,
+        inputTokens,
+        outputTokens: scoped.reduce((total, entry) => total + entry.tiers.output, 0),
+        totalTokens: scoped.reduce((total, entry) => total + totalTokens(entry), 0),
+        label: labelOf(scoped),
+        ...(billableInput > 0
+            ? {
+                cacheHitRate: scoped.reduce((total, entry) => total + entry.tiers["cache-read"], 0) / billableInput,
+            }
+            : {}),
+        stages,
+        requirements: uniqueSorted(scoped.map((entry) => entry.requirement)),
+        models: uniqueSorted(scoped.map((entry) => entry.model)),
+        harnesses: uniqueSorted(scoped.map((entry) => entry.harness)),
+    };
+}
+export function serializeTaskUsage(summary) {
+    if (!summary.entries)
+        return `No usage recorded for workflow ${summary.workflow}. Correlate runs with \`aiw usage-sidecar record --workflow=${summary.workflow}\`.`;
+    return [
+        `workflow: ${summary.workflow} (${summary.entries} entries, ${summary.label})`,
+        `input_tokens: ${summary.inputTokens.toLocaleString("en-US")} (cache-read + fresh-input + cache-write)`,
+        `output_tokens: ${summary.outputTokens.toLocaleString("en-US")}`,
+        `total_tokens: ${summary.totalTokens.toLocaleString("en-US")}`,
+        ...(summary.cacheHitRate === undefined
+            ? []
+            : [`cache_hit_rate: ${Math.round(summary.cacheHitRate * 100)}%`]),
+        ...(summary.models.length ? [`models: ${summary.models.join(", ")}`] : []),
+        ...(summary.harnesses.length ? [`harnesses: ${summary.harnesses.join(", ")}`] : []),
+        ...(summary.requirements.length ? [`requirements: ${summary.requirements.join(", ")}`] : []),
+        "by stage:",
+        ...summary.stages.map(({ stage, tokens, label, models }) => `  - ${stage}: ${tokens.toLocaleString("en-US")} tokens (${label}${models.length ? `; ${models.join(", ")}` : ""})`),
+        "metric: tokens are model-invariant — comparable across model routing changes and harness migrations.",
+    ].join("\n");
+}

package/dist/heartbeat.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Session heartbeat: event-driven cache-TTL management.
+ *
+ * Harness hooks (Claude Code Stop/UserPromptSubmit, Gemini
+ * PostInvocation/Stop, Codex turn notifications) call `aiw heartbeat` on
+ * every event. Each beat measures the gap since the previous one:
+ *
+ * - gap < warn (default 4 min): active session, nothing to do;
+ * - warn <= gap < ttl (default 5 min): the provider cache is still warm —
+ *   this request just read it at cache price — so a compact checkpoint is
+ *   written now: if the session goes idle past the TTL, the next resume
+ *   loads a small prefix instead of rebuilding the full one;
+ * - gap >= ttl: the cache already expired and this request paid the full
+ *   rebuild — a compact checkpoint is written so the *next* gap hurts an
+ *   order of magnitude less.
+ *
+ * The guarantee: a session never pays the full-price prefix rebuild twice
+ * in a row on the same context. No timers, no keep-alive pings: the gap is
+ * always measured on the next beat, which costs nothing locally.
+ *
+ * Timestamps are legitimate here: this is operational state (like workflow
+ * checkpoints), not a deterministic report.
+ */
+export declare const HEARTBEAT_SCHEMA = 1;
+export declare const HEARTBEAT_STATE_PATH = "heartbeats.yml";
+export declare const HEARTBEAT_WARN_SECONDS = 240;
+export declare const HEARTBEAT_TTL_SECONDS = 300;
+export type HeartbeatDecision = "session-start" | "active" | "compact-before-expiry" | "cache-expired";
+export type HeartbeatSession = {
+    id: string;
+    lastBeat: string;
+    beats: number;
+    status: "warm" | "cold";
+    actions: number;
+};
+export type HeartbeatState = {
+    schema: number;
+    sessions: HeartbeatSession[];
+};
+export type HeartbeatOutcome = {
+    decision: HeartbeatDecision;
+    gapSeconds: number | undefined;
+    session: HeartbeatSession;
+    /** Set when a compact checkpoint should be written (decision tier warn/ttl). */
+    checkpoint: {
+        session: string;
+        index: number;
+        decision: HeartbeatDecision;
+    } | undefined;
+};
+export declare function validateHeartbeatThresholds(warnSeconds: number, ttlSeconds: number): void;
+export declare function emptyHeartbeatState(): HeartbeatState;
+export declare function parseHeartbeatState(content: string): HeartbeatState;
+export declare function serializeHeartbeatState(state: HeartbeatState): string;
+/** Record a beat and decide. `now` is injectable for deterministic tests. */
+export declare function recordBeat(state: HeartbeatState, sessionId: string, now: Date, warnSeconds?: number, ttlSeconds?: number): {
+    state: HeartbeatState;
+    outcome: HeartbeatOutcome;
+};
+export declare function serializeHeartbeatCheckpoint(checkpoint: NonNullable<HeartbeatOutcome["checkpoint"]>, gapSeconds: number, ttlSeconds: number): string;
+export declare function describeHeartbeatOutcome(outcome: HeartbeatOutcome): string;

package/dist/heartbeat.js

@@ -0,0 +1,158 @@
+import { parseDocument } from "yaml";
+/**
+ * Session heartbeat: event-driven cache-TTL management.
+ *
+ * Harness hooks (Claude Code Stop/UserPromptSubmit, Gemini
+ * PostInvocation/Stop, Codex turn notifications) call `aiw heartbeat` on
+ * every event. Each beat measures the gap since the previous one:
+ *
+ * - gap < warn (default 4 min): active session, nothing to do;
+ * - warn <= gap < ttl (default 5 min): the provider cache is still warm —
+ *   this request just read it at cache price — so a compact checkpoint is
+ *   written now: if the session goes idle past the TTL, the next resume
+ *   loads a small prefix instead of rebuilding the full one;
+ * - gap >= ttl: the cache already expired and this request paid the full
+ *   rebuild — a compact checkpoint is written so the *next* gap hurts an
+ *   order of magnitude less.
+ *
+ * The guarantee: a session never pays the full-price prefix rebuild twice
+ * in a row on the same context. No timers, no keep-alive pings: the gap is
+ * always measured on the next beat, which costs nothing locally.
+ *
+ * Timestamps are legitimate here: this is operational state (like workflow
+ * checkpoints), not a deterministic report.
+ */
+export const HEARTBEAT_SCHEMA = 1;
+export const HEARTBEAT_STATE_PATH = "heartbeats.yml";
+export const HEARTBEAT_WARN_SECONDS = 240;
+export const HEARTBEAT_TTL_SECONDS = 300;
+export function validateHeartbeatThresholds(warnSeconds, ttlSeconds) {
+    for (const [name, value] of [
+        ["warn", warnSeconds],
+        ["ttl", ttlSeconds],
+    ])
+        if (!Number.isInteger(value) || value <= 0)
+            throw new Error(`Heartbeat ${name} threshold must be a positive integer (seconds).`);
+    if (warnSeconds >= ttlSeconds)
+        throw new Error("Heartbeat warn threshold must be smaller than the TTL threshold.");
+}
+export function emptyHeartbeatState() {
+    return { schema: HEARTBEAT_SCHEMA, sessions: [] };
+}
+export function parseHeartbeatState(content) {
+    if (!content.trim())
+        return emptyHeartbeatState();
+    const document = parseDocument(content);
+    if (document.errors.length)
+        throw new Error("Heartbeat state is not valid YAML.");
+    const schema = document.get("schema");
+    if (schema !== HEARTBEAT_SCHEMA)
+        throw new Error(`Heartbeat state schema must be version ${HEARTBEAT_SCHEMA}.`);
+    const sessionsNode = document.get("sessions");
+    const sessions = [];
+    if (sessionsNode !== null && sessionsNode !== undefined) {
+        const items = Array.isArray(sessionsNode)
+            ? sessionsNode
+            : (sessionsNode.items ?? []);
+        for (const raw of items) {
+            const read = (key) => typeof raw.get === "function" ? raw.get(key) : raw[key];
+            const id = String(read("id"));
+            if (!id.trim())
+                throw new Error("Heartbeat session id must not be empty.");
+            const lastBeat = String(read("last_beat"));
+            if (Number.isNaN(Date.parse(lastBeat)))
+                throw new Error(`Heartbeat session ${id} has an invalid last_beat timestamp.`);
+            sessions.push({
+                id,
+                lastBeat,
+                beats: Number(read("beats")),
+                status: read("status") === "cold" ? "cold" : "warm",
+                actions: Number(read("actions") ?? 0),
+            });
+        }
+    }
+    return { schema: HEARTBEAT_SCHEMA, sessions };
+}
+export function serializeHeartbeatState(state) {
+    const lines = [`schema: ${state.schema}`, "sessions:"];
+    if (!state.sessions.length)
+        lines.push("  []");
+    for (const session of state.sessions)
+        lines.push(`  - id: ${session.id}`, `    last_beat: ${session.lastBeat}`, `    beats: ${session.beats}`, `    status: ${session.status}`, `    actions: ${session.actions}`);
+    return lines.join("\n") + "\n";
+}
+/** Record a beat and decide. `now` is injectable for deterministic tests. */
+export function recordBeat(state, sessionId, now, warnSeconds = HEARTBEAT_WARN_SECONDS, ttlSeconds = HEARTBEAT_TTL_SECONDS) {
+    if (!sessionId.trim())
+        throw new Error("Heartbeat session id must not be empty.");
+    validateHeartbeatThresholds(warnSeconds, ttlSeconds);
+    const iso = now.toISOString();
+    const previous = state.sessions.find((session) => session.id === sessionId);
+    let decision;
+    let gapSeconds;
+    if (!previous) {
+        decision = "session-start";
+    }
+    else {
+        gapSeconds = Math.max(0, Math.round((now.getTime() - Date.parse(previous.lastBeat)) / 1000));
+        decision =
+            gapSeconds < warnSeconds
+                ? "active"
+                : gapSeconds < ttlSeconds
+                    ? "compact-before-expiry"
+                    : "cache-expired";
+    }
+    const updated = {
+        id: sessionId,
+        lastBeat: iso,
+        beats: (previous?.beats ?? 0) + 1,
+        status: decision === "cache-expired" ? "cold" : "warm",
+        actions: previous?.actions ?? 0,
+    };
+    const shouldCheckpoint = decision === "compact-before-expiry" || decision === "cache-expired";
+    if (shouldCheckpoint)
+        updated.actions += 1;
+    const sessions = state.sessions.filter((session) => session.id !== sessionId).concat(updated);
+    sessions.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    return {
+        state: { schema: state.schema, sessions },
+        outcome: {
+            decision,
+            gapSeconds,
+            session: updated,
+            checkpoint: shouldCheckpoint
+                ? { session: sessionId, index: updated.actions, decision }
+                : undefined,
+        },
+    };
+}
+export function serializeHeartbeatCheckpoint(checkpoint, gapSeconds, ttlSeconds) {
+    return ([
+        "schema: 1",
+        `session: ${checkpoint.session}`,
+        `decision: ${checkpoint.decision}`,
+        `gap_seconds: ${gapSeconds}`,
+        `ttl_seconds: ${ttlSeconds}`,
+        "action: resume from this checkpoint; prefer harness compaction (/compact) before continuing the session",
+    ].join("\n") + "\n");
+}
+export function describeHeartbeatOutcome(outcome) {
+    const gap = outcome.gapSeconds === undefined ? "" : ` (gap ${formatGap(outcome.gapSeconds)})`;
+    switch (outcome.decision) {
+        case "session-start":
+            return `heartbeat: session ${outcome.session.id} started`;
+        case "active":
+            return `heartbeat: session ${outcome.session.id} active${gap}`;
+        case "compact-before-expiry":
+            return `heartbeat: session ${outcome.session.id} idle${gap} — cache still warm; compact checkpoint #${outcome.session.actions} saved for a cheap resume`;
+        case "cache-expired":
+            return `heartbeat: session ${outcome.session.id} idle${gap} — cache expired and this request paid the rebuild; compact checkpoint #${outcome.session.actions} saved so the next gap is cheap`;
+    }
+}
+function formatGap(seconds) {
+    if (seconds < 60)
+        return `${seconds}s`;
+    const minutes = Math.floor(seconds / 60);
+    const rest = seconds % 60;
+    return rest ? `${minutes}m${rest}s` : `${minutes}m`;
+}