hermes log forwarding adapter (LLP 0118-0125)

[philcunliffe]

Implements the @hypaware/hermes log-forwarding adapter designed in the LLP 0118-0125 cluster (spec 0118, design 0122, plan 0123).

Tasks (all verified-merged, --no-ff)

• T1 engines bump to >=22.12 + read-only state.db reader (node:sqlite)
• T2 projector to AiGatewayProjectedExchange (deterministic ids, usage-policy skip, session-end part)
• T3 backfill provider (--since windowing)
• T4 poll source with per-session watermarks
• T5 plugin wiring (manifest/config/activate, workspace registration)
• T6 hermetic smoke (hermes_backfill_roundtrip)

Neutral pipeline: design-first cluster merged to master (#331), seeded integration/hermes-log-forwarding, implemented by the neutral wave-loop across 6 dependency-ordered tasks. Held for review.

@ref LLP 0122 [implements]

Change-Set: hermes-log-forwarding

[philcunliffe]

Neutral review - @hypaware/hermes log-forwarding adapter (T1-T6)

Verdict: clean. No actionable correctness, determinism, spec-adherence, or style defect. The change set is purely additive at the plugin seam and faithfully realizes LLP 0118 / 0119 / 0120 / 0121 / 0122 / 0124 / 0125. Nothing pushed.

Reviewed head 57278bc in an isolated worktree.

What I verified

• Determinism (spec R2).mintHermesMessageId(sessionId, messageId, partIndex) -> hermes-<s>-<m>-<p> and mintHermesSessionEndId -> hermes-<s>-session_end are pure functions of hermes's own stable integer keys; with all-digit segments and a fixed 3-dash shape they cannot alias, and session_end never collides with a numeric part. Whole-session re-projection every time keeps message_index/previous_message_id/part_id independent of observation order. The idempotency guarantee ultimately rests on the shared aiGatewayBackfillMaterializer pre-write part_id dedupe (ai-gateway/src/dataset.js), which scans all partitions of ai_gateway_messages (scanExistingPartIds -> discoverCachePartitions({datasets:[...]})), so poll-written (hermes segment) and backfill-written rows dedupe against each other. Empirically: the smoke's second hyp backfill hermes writes rows_written === 0.
• Projection. Provider normalization (base_url host map, fallback to billing_provider, never hermes), tool-call/reasoning/text part expansion with one-carrier usage on the last part (@ref LLP 0035#one-carrier), and the synthetic session-end part emitted exactly once when ended_at is set and absent while open (verified in hermes-projector.test.js).
• Watermark/source (R7/R9). Missing-store idle mode (logged once, re-probed each tick, status() reports it), per-session {max_message_id, ended_at} persisted atomically, changed-sessions-only re-projection, ended_at NULL->set re-trigger with no new messages, stop() clears the timer and closes the db, hermes.poll span with component: 'hermes'.
• Usage-policy skip (R3, LLP 0050). Resolved over the effective scope (real cwd, or the ~/.hermes/channels/<source> path for channel sessions) before any row is built; the smoke drops a real .hypignore session via the production resolver (not a test stub).
• Channel scope (R10, LLP 0124).cwd stamped ~/.hermes/channels/<source>, real daemon cwd preserved in attributes.hermes.real_cwd.
• sqlite reader (R5, LLP 0119/0122#sqlite).DatabaseSync { readOnly: true }, activation probe -> typed sqlite_unavailable refusal instead of a crash, bounded SQLITE_BUSY/LOCKED retry -> typed sqlite_busy that degrades status.
• Wiring (LLP 0121). Manifest requires @hypaware/ai-gateway, contributes config_sections+sources, no datasets; registered in V1_BUNDLED_PLUGIN_ALLOWLIST beside claude/codex; the only non-hermes edits are the bundled list, the cli_bundled_plugins_activated skip count (5->6), the CI node 22/24 matrix, and the >=22.12 engines bump. Nothing touches ai-gateway, the cache schema, settlement, or any sink.
• Smoke (T6). Asserts rows land with client_name='hermes'/provider='openai', zero new rows on rerun, the ignored-cwd session absent, and the internal telemetry (backfill.provider_finish/backfill.write/hermes.backfill.scan_complete/plugin.hermes.usage_policy_drop). Stable DEV_RUN_ID/smoke_name/smoke_step; discovered by filename.
• Style (CLAUDE.md). No semicolons, no em dashes, JSDoc-only types, no inline import('...') types, root-anchored .js type-import specifiers. All @ref anchors resolve (checked 0030#decision, 0032#remote-redaction/#repo-commit-nodes, 0035#one-carrier, 0120#row-semantics, 0122 anchors, 0123#tasks).

Local results

• node --test test/plugins/hermes-*.test.js: 62/62 pass.
• npm test: 2405 pass, 7 fail - all 7 are the pre-existing leave-command.test.js failures unrelated to this PR.
• npm run smoke -- hermes_backfill_roundtrip: ok.
• npm run typecheck: clean.

Non-blocking notes for the maintainer (no change made)

1. Session token totals are invisible to the canonical usage report (design tradeoff, not a code defect). Hermes's messages table carries only a single token_count per row, so per-message usage projects as { total_tokens } only - never the LLP 0035 input_tokens/output_tokens/cache_*/reasoning_tokens split. That split exists only at session level and rides the synthetic session-end part, which is deliberately role: 'system' (projector.js sessionEndMessage). The flagship usage report SQL sums ... WHERE role='assistant' AND attributes.usage IS NOT NULL (see hypaware-ai-usage-report/SKILL.md), so hermes sessions report 0 input/output/cache/reasoning tokens there, open or ended. LLP 0122#session-end-part reasons about this choice explicitly (role='system' to avoid double-counting a SUM over assistant rows), and the code matches that accepted design - so this is a design-level call, not a code bug, and I did not alter it. Worth deciding whether the flagship "hermes alongside Claude/Codex" motivation (LLP 0118) is met when the standard report shows zero token cost for hermes; a follow-up could either land the session totals on the last assistant row (safe: hermes assistant rows carry no input_tokens, so no double count) or teach the usage report to read the end part.
2. reload() with a changed state_db path can bleed a stale watermark (low, edge).source.js reload sets runner.watermark = {} when the path changes, but the next tryOpen immediately re-reads readHermesWatermark(runner.stateDir) - and the watermark sidecar is keyed by stateDir, not by db path. Since hermes session ids are store-scoped integers starting at 1, the previous db's marks would suppress re-projection of the new db's low-id sessions. This only bites the profile-switching path that LLP 0122 open-question [codex] Remove OpenTelemetry npm dependencies #2 already defers as future work, so it is a latent limitation rather than a regression.