@multileaf/ai-workflow 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -4,6 +4,31 @@ All notable changes to this project are documented in this file. The format foll
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-10-30
+
+### Added
+
+- Typed blocking reasons with exact continuations (OPP-004): every workflow, gate, and approval blocking exit emits a stable reason code plus either an exact runnable `aiw` continuation or an explicit terminal statement. With `--json`, blocks return machine-readable `reason_code` and `next_command`/`next_action`/`terminal` fields. `docs/continuation-inventory.md` maps every code and is kept in parity with the registry by a CI test.
+- `aiw risk assess` (OPP-002): read-only, content-based risk classification for working-tree or `--base-ref` changes. Six high-risk categories (data/irreversible, security, consumed contracts, concurrency, delivery/environment, untested regression) classify by what changed, never by size: documentation-only diffs are `passive`; size never decides. Deterministic and offline by default; `--escalate-item 1-6 --escalate-reason` raises and never lowers a tier; `risk_due: yes` names an exact runnable next command (`aiw.risk-assessment/v1` JSON envelope).
+- Light lane (OPP-001): a human-chosen `aiw task start --lane=light --lane-reason=...` for small, understood work — the resume test decides (resumable from the request plus `git diff`). No durable spec/plan artifacts; validation evidence is recorded via `aiw task evidence` and completion requires at least one entry; the lane and rationale are written into the session and approval ledger for audit. Stage commands block with `lane_escalation_required`; `aiw task escalate --reason` moves the workflow to the full lane (one-way, evidence preserved). The full lane remains the default and unchanged.
+- Emission ≠ usability policy and command ratchet (OPP-006): messages naming an `aiw` command must have a test that executes it. A ratchet test executes every command named by the generated skills and READMEs and fails on unknown commands.
+- Friction benchmark (OPP-005): `scripts/friction-bench.mjs` drives packaged-CLI journeys and classifies every non-success exit as in-band / out-of-band / dead-end, executing printed continuations to verify they resolve. CI enforces a zero-dead-end budget; the release gate re-verifies budget and determinism. Baseline: in-band 5, out-of-band 5, dead-end 0.
+- Adversarial review skills (OPP-003): `review-judge-a`, `review-judge-b`, and `review-refuter` ship in the self-hosting package. Two blind judges review independently; severe findings require a reproducing command or self-proving `file:line` citations and otherwise degrade to advisory; only corroborated severe findings block. Refuter command execution is permission-gated (default: evidence reading with an explicit no-command-executed marker, isolated directory, no network). Human acceptance of the review outcome is unchanged.
+- Workflow proportionality documentation: [ADR-001](.context/adrs/ADR-001-odd-rdd-proportionality-scope.md) records the ODD/RDD analysis — six implemented opportunities plus advisory-only model-integration opportunities (OPP-007/008) deliberately deferred until field exposure.
+
+### Fixed
+
+- `aiw risk assess` no longer truncates paths of tracked-modified files (the porcelain fixed-width column was destroyed by line trimming) and no longer flags `.aiw/` managed state (for example `lock.yml`) as concurrency risk.
+- `aiw risk` without a subcommand now prints its own typed usage instead of the general command dump.
+
+## [0.9.1] - 2026-10-24
+
+### Fixed
+
+- Workflow capabilities are always recommended: the seven SDD capabilities (brainstorming, ticket-driven-development, requirements-specification, implementation-planning, technical-design, code-review, verification) are marked universal and are recommended for any project, including scans with no detected signals. Previously a project without languages, frameworks, package manager, tests, linter, or CI received zero recommendations; stack-dependent capabilities still require their evidence.
+
+## [0.9.0] - 2026-10-21
+
 ## [0.8.0] - 2026-10-20
 
 ### Added
@@ -14,6 +39,8 @@ All notable changes to this project are documented in this file. The format foll
 - 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
 

package/README.md

@@ -14,6 +14,7 @@ AI-assisted development often relies on implicit prompts, duplicated configurati
 - skills, rules, agents, hooks, and templates are versioned resources;
 - target-specific files are generated through adapters;
 - quality gates and checkpoints provide completion evidence;
+- ceremony scales with the consequence of the change — risk-based lanes instead of uniform ceremony;
 - context is filtered and loaded only when needed to reduce token usage;
 - package-declared sensitive capabilities are evaluated by policy boundaries.
 
@@ -114,7 +115,7 @@ flowchart TD
 
 ## The SDD workflow
 
-AI Workflow supports an end-to-end specification-driven development cycle:
+AI Workflow supports an end-to-end specification-driven development cycle. Ceremony is proportional: `aiw risk assess` classifies each change by content, and small, understood work may run in a human-chosen light lane (evidence entries instead of durable artifacts) while substantial work runs the staged sequence below. The current end-to-end flow, both lanes, and the CI enforcement layer are diagrammed in [Architecture — Current flow](docs/architecture.md#current-flow).
 
 ```mermaid
 flowchart TD
@@ -205,6 +206,16 @@ npx @multileaf/ai-workflow recommend --select=typescript-quality,verification
 # Track a feature from its first artifact through final human approval.
 npx @multileaf/ai-workflow workflow start
 
+# Small, understood change? The light lane skips durable spec/plan artifacts
+# (human-chosen via the resume test) and records validation evidence instead.
+npx @multileaf/ai-workflow task start --ticket=TEAM-7 --lane=light --lane-reason="small fix, resumable from request"
+npx @multileaf/ai-workflow task evidence --validation="npm test: passed"
+npx @multileaf/ai-workflow workflow complete
+# If scope grows: aiw task escalate --reason=...
+
+# Classify the risk of current changes (read-only; content, not size).
+npx @multileaf/ai-workflow risk assess [--base-ref=<ref>] [--escalate-item=1-6 --escalate-reason=text] [--json]
+
 # Or start directly from a ticket / already-clear requirement (no brainstorm needed).
 npx @multileaf/ai-workflow task start --ticket=PROJ-142 --title="Add export endpoint"
 npx @multileaf/ai-workflow task status

package/dist/blocking-reasons.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Typed reason codes and exact continuations for every blocking CLI exit.
+ *
+ * Contract (OPP-004, REQ-OPP-004): a blocking output must carry a stable
+ * reason code plus either an exact runnable continuation or an explicit
+ * terminal statement. A message may name a command only when running that
+ * command resolves the block it was printed for. See ADR-001 and
+ * docs/opportunities/OPP-004-exact-continuation-commands.md.
+ */
+export declare const BLOCKING_REASON_CODES: readonly ["gate_evidence_missing", "gate_incomplete", "stage_prerequisite_pending", "stage_prerequisite_unresolved", "stage_awaiting_approval", "stage_already_approved", "approval_evidence_missing", "approval_stale", "approval_gate_missing", "lane_escalation_required", "light_evidence_missing"];
+export type BlockingReasonCode = (typeof BLOCKING_REASON_CODES)[number];
+/** How the user or agent gets past a block. Exactly one of three kinds. */
+export type BlockingContinuation = 
+/** An exact runnable `aiw` command with every argument resolved. */
+{
+    kind: "command";
+    command: string;
+}
+/** A concrete non-command step (for example, authoring an artifact). */
+ | {
+    kind: "action";
+    description: string;
+}
+/** No in-line continuation exists; a human decision is required. */
+ | {
+    kind: "terminal";
+    humanDecision: string;
+};
+/** Resolved context used by continuation producers. */
+export type BlockingContext = {
+    stage?: string;
+    pendingStages?: string[];
+    unresolvedStages?: string[];
+    artifactPath?: string;
+    gateIssues?: string[];
+    /** Context-specific human message preferred over the generic definition text. */
+    detail?: string;
+};
+export type BlockingReasonDefinition = {
+    code: BlockingReasonCode;
+    description: string;
+    continuation: (context: BlockingContext) => BlockingContinuation;
+};
+export declare const BLOCKING_REASON_INVENTORY: Readonly<Record<BlockingReasonCode, BlockingReasonDefinition>>;
+export declare function getBlockingReasonDefinition(code: string): BlockingReasonDefinition;
+export type BlockingResult = {
+    code: BlockingReasonCode;
+    /** Explanation of the block without continuation instructions. */
+    message: string;
+    continuation: BlockingContinuation;
+};
+export declare function describeBlockingReason(code: BlockingReasonCode, context: BlockingContext): BlockingResult;
+/** Error thrown by blocking CLI paths; carries the typed result for `--json` output. */
+export declare class BlockingError extends Error {
+    readonly result: BlockingResult;
+    constructor(result: BlockingResult);
+}
+export declare function formatBlockingOutput(result: BlockingResult): string;
+export type BlockingJson = {
+    reason_code: BlockingReasonCode;
+    next_command?: string;
+    next_action?: string;
+    terminal?: boolean;
+};
+export declare function blockingResultToJson(result: BlockingResult): BlockingJson;
+/** Markdown continuation inventory for docs generation and CI parity checks. */
+export declare function exportContinuationInventoryMarkdown(): string;

package/dist/blocking-reasons.js

@@ -0,0 +1,181 @@
+/**
+ * Typed reason codes and exact continuations for every blocking CLI exit.
+ *
+ * Contract (OPP-004, REQ-OPP-004): a blocking output must carry a stable
+ * reason code plus either an exact runnable continuation or an explicit
+ * terminal statement. A message may name a command only when running that
+ * command resolves the block it was printed for. See ADR-001 and
+ * docs/opportunities/OPP-004-exact-continuation-commands.md.
+ */
+export const BLOCKING_REASON_CODES = [
+    "gate_evidence_missing",
+    "gate_incomplete",
+    "stage_prerequisite_pending",
+    "stage_prerequisite_unresolved",
+    "stage_awaiting_approval",
+    "stage_already_approved",
+    "approval_evidence_missing",
+    "approval_stale",
+    "approval_gate_missing",
+    "lane_escalation_required",
+    "light_evidence_missing",
+];
+function command(commandText) {
+    return { kind: "command", command: commandText };
+}
+function action(description) {
+    return { kind: "action", description };
+}
+function terminal(humanDecision) {
+    return { kind: "terminal", humanDecision };
+}
+function firstStage(stages) {
+    return stages && stages.length > 0 ? stages[0] : undefined;
+}
+export const BLOCKING_REASON_INVENTORY = {
+    gate_evidence_missing: {
+        code: "gate_evidence_missing",
+        description: "The quality gate is blocked because the required evidence artifact is missing.",
+        continuation: (context) => context.stage && context.artifactPath
+            ? action(`Create the required artifact at ${context.artifactPath}, then run \`aiw gate ${context.stage}\`.`)
+            : terminal("Decide which stage artifact to author before gating."),
+    },
+    gate_incomplete: {
+        code: "gate_incomplete",
+        description: "The quality gate found completeness issues in the stage artifact.",
+        continuation: (context) => context.stage
+            ? action(`Fix the gate findings in the stage artifact${context.artifactPath ? ` (${context.artifactPath})` : ""}, then run \`aiw gate ${context.stage}\` again.`)
+            : terminal("Fix the gate findings, then rerun the stage gate."),
+    },
+    stage_prerequisite_pending: {
+        code: "stage_prerequisite_pending",
+        description: "A previous stage is awaiting human approval before this stage can start.",
+        continuation: (context) => {
+            const pending = firstStage(context.pendingStages);
+            return pending
+                ? command(`aiw approve ${pending}`)
+                : terminal("Review the pending previous stage with a human.");
+        },
+    },
+    stage_prerequisite_unresolved: {
+        code: "stage_prerequisite_unresolved",
+        description: "Previous stages need human approval or an accepted optional skip before this stage can start.",
+        continuation: (context) => {
+            const unresolved = firstStage(context.unresolvedStages);
+            return unresolved
+                ? command(`aiw approve ${unresolved}`)
+                : terminal("Resolve the previous stages with a human before continuing.");
+        },
+    },
+    stage_awaiting_approval: {
+        code: "stage_awaiting_approval",
+        description: "This stage is awaiting human approval; approve or reject it before continuing.",
+        continuation: (context) => context.stage
+            ? command(`aiw approve ${context.stage}`)
+            : terminal("A human must approve or reject the pending stage."),
+    },
+    stage_already_approved: {
+        code: "stage_already_approved",
+        description: "This stage is already approved; changed evidence requires rerunning its quality gate.",
+        continuation: (context) => context.stage
+            ? command(`aiw gate ${context.stage}`)
+            : terminal("A human must decide whether to rerun the gate for the changed evidence."),
+    },
+    approval_evidence_missing: {
+        code: "approval_evidence_missing",
+        description: "Approval cannot be recorded because the stage evidence artifact is missing.",
+        continuation: (context) => context.stage && context.artifactPath
+            ? action(`Create the required artifact at ${context.artifactPath}, then run \`aiw approve ${context.stage}\`.`)
+            : terminal("Decide which stage artifact to author before approving."),
+    },
+    approval_stale: {
+        code: "approval_stale",
+        description: "The artifact changed after review; its approval is stale and the gate must run again.",
+        continuation: (context) => context.stage
+            ? command(`aiw gate ${context.stage}`)
+            : terminal("A human must decide whether to rerun the gate for the changed artifact."),
+    },
+    approval_gate_missing: {
+        code: "approval_gate_missing",
+        description: "No passing quality gate is recorded for this stage; gate it before approving.",
+        continuation: (context) => context.stage
+            ? command(`aiw gate ${context.stage}`)
+            : terminal("A human must decide whether to gate the stage before approving."),
+    },
+    lane_escalation_required: {
+        code: "lane_escalation_required",
+        description: "Light-lane workflows do not author stage artifacts; escalate to the full lane to continue.",
+        continuation: () => action("Run `aiw task escalate --reason=<why scope grew>` to move this workflow to the full lane; recorded light-lane evidence is preserved."),
+    },
+    light_evidence_missing: {
+        code: "light_evidence_missing",
+        description: "A light-lane workflow cannot complete without at least one recorded validation entry.",
+        continuation: () => action("Run `aiw task evidence --validation=<command and result>` at least once, then `aiw workflow complete`."),
+    },
+};
+export function getBlockingReasonDefinition(code) {
+    const definition = BLOCKING_REASON_INVENTORY[code];
+    if (!definition)
+        throw new Error(`Unknown blocking reason code: ${code}`);
+    return definition;
+}
+export function describeBlockingReason(code, context) {
+    const definition = getBlockingReasonDefinition(code);
+    return {
+        code,
+        message: context.detail ?? definition.description,
+        continuation: definition.continuation(context),
+    };
+}
+/** Error thrown by blocking CLI paths; carries the typed result for `--json` output. */
+export class BlockingError extends Error {
+    result;
+    constructor(result) {
+        super(formatBlockingOutput(result));
+        this.name = "BlockingError";
+        this.result = result;
+    }
+}
+export function formatBlockingOutput(result) {
+    const prefix = `${result.message} [reason: ${result.code}]`;
+    switch (result.continuation.kind) {
+        case "command":
+            return `${prefix} Next: run \`${result.continuation.command}\`.`;
+        case "action":
+            return `${prefix} Next: ${result.continuation.description}`;
+        case "terminal":
+            return `${prefix} Terminal: no automatic continuation. ${result.continuation.humanDecision}`;
+    }
+}
+export function blockingResultToJson(result) {
+    switch (result.continuation.kind) {
+        case "command":
+            return { reason_code: result.code, next_command: result.continuation.command };
+        case "action":
+            return { reason_code: result.code, next_action: result.continuation.description };
+        case "terminal":
+            return { reason_code: result.code, terminal: true };
+    }
+}
+const CONTINUATION_KIND_LABEL = {
+    command: "runnable command",
+    action: "explicit action",
+    terminal: "terminal (human decision)",
+};
+/** Markdown continuation inventory for docs generation and CI parity checks. */
+export function exportContinuationInventoryMarkdown() {
+    const rows = BLOCKING_REASON_CODES.map((code) => {
+        const definition = getBlockingReasonDefinition(code);
+        return `| \`${code}\` | ${definition.description} | ${CONTINUATION_KIND_LABEL[commandKind(code)]} |`;
+    });
+    return ["| Reason code | Description | Continuation |", "| --- | --- | --- |", ...rows].join("\n");
+}
+function commandKind(code) {
+    const sample = describeBlockingReason(code, {
+        stage: "specification",
+        pendingStages: ["brainstorming"],
+        unresolvedStages: ["brainstorming"],
+        artifactPath: ".aiw/generated/specs/specification.md",
+    });
+    return sample.continuation.kind;
+}

package/dist/command-evidence.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Emission ≠ usability enforcement (OPP-006, REQ-OPP-006).
+ *
+ * A test that verifies a message was emitted does not verify it is usable.
+ * Any user-facing artifact (docs, generated skills, blocking output) that
+ * names an `aiw` command must be covered by a test that proves the command
+ * is real — the source lesson: a shipped message named a command nobody had
+ * ever run, for months, with green coverage.
+ *
+ * This helper extracts `aiw ...` and `npx @multileaf/ai-workflow ...`
+ * invocations from artifact text so tests can execute them.
+ */
+export type CommandMention = {
+    /** Normalized invocation: command and subcommand words only, no flags. */
+    command: string;
+    /** Source label for diagnostics. */
+    source: string;
+};
+/** Extract normalized command mentions (command + optional subcommand, no flags). */
+export declare function extractAiwCommands(text: string, source?: string): CommandMention[];
+/**
+ * Informational mentions excluded from execution evidence. Every entry needs
+ * a justification; entries are exact normalized commands.
+ */
+export declare const INFORMATIONAL_ALLOWLIST: readonly {
+    command: string;
+    justification: string;
+}[];
+/** First token (the command word) used for recognition checks. */
+export declare function commandWord(mention: CommandMention): string;
+/** Signature of the general usage dump printed for unknown commands. */
+export declare const UNKNOWN_COMMAND_SIGNATURE = "aiw install [--target target] | workflow";

package/dist/command-evidence.js

@@ -0,0 +1,61 @@
+/**
+ * Emission ≠ usability enforcement (OPP-006, REQ-OPP-006).
+ *
+ * A test that verifies a message was emitted does not verify it is usable.
+ * Any user-facing artifact (docs, generated skills, blocking output) that
+ * names an `aiw` command must be covered by a test that proves the command
+ * is real — the source lesson: a shipped message named a command nobody had
+ * ever run, for months, with green coverage.
+ *
+ * This helper extracts `aiw ...` and `npx @multileaf/ai-workflow ...`
+ * invocations from artifact text so tests can execute them.
+ */
+const INVOCATION_PATTERN = /(^|`|\n)(?:aiw|npx @multileaf\/ai-workflow) ([a-z][a-z-]*)(?: ([a-z][a-z-]*))?/g;
+/** English words that must never be captured as a subcommand. */
+const STOP_WORDS = new Set([
+    "and",
+    "or",
+    "the",
+    "a",
+    "to",
+    "then",
+    "is",
+    "in",
+    "with",
+    "before",
+    "after",
+    "you",
+    "see",
+    "for",
+    "that",
+    "helps",
+    "tool",
+]);
+/** Extract normalized command mentions (command + optional subcommand, no flags). */
+export function extractAiwCommands(text, source = "text") {
+    const mentions = [];
+    for (const match of text.matchAll(INVOCATION_PATTERN)) {
+        const subcommand = match[3] && !STOP_WORDS.has(match[3]) ? match[3] : undefined;
+        const command = subcommand ? `${match[2]} ${subcommand}` : match[2];
+        if (!mentions.some((mention) => mention.command === command && mention.source === source)) {
+            mentions.push({ command, source });
+        }
+    }
+    return mentions;
+}
+/**
+ * Informational mentions excluded from execution evidence. Every entry needs
+ * a justification; entries are exact normalized commands.
+ */
+export const INFORMATIONAL_ALLOWLIST = [
+    {
+        command: "aiw install",
+        justification: "Executed by the install e2e suite; README form includes --target variants.",
+    },
+];
+/** First token (the command word) used for recognition checks. */
+export function commandWord(mention) {
+    return mention.command.split(" ")[0];
+}
+/** Signature of the general usage dump printed for unknown commands. */
+export const UNKNOWN_COMMAND_SIGNATURE = "aiw install [--target target] | workflow";

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`;
+}