harn semantic

harn semantic <subcommand> [options]

harn semantic turns the bounded facts in an active Event Ledger V3 generation into a broader read model for operator-facing surfaces. The generated meaning is derived state. It lives separately under .harnery/semantic/v2/ and never writes back to the canonical ledger.

Every claim carries the event IDs that support it. Invalid output, an unavailable model, and a rate-limited request produce typed receipts instead of silently keeping old meaning.

Model routing

The source harness determines the reader. Harnery does not fall back to a model from another harness.

Source harness	Configured reader
Claude Code	Haiku 4.5
Codex	GPT-5.6 Luna
Cursor	Composer 2.5

The adapters request those exact models. When a harness does not attest the executed model in its result envelope, the stored reader records model_attestation: "requested-only" rather than claiming that the model was verified.

Subcommands

harn semantic once                         # run one bounded pass
harn semantic once --calls-per-hour 12     # use a lower local ceiling
harn semantic service start                # explicitly start or resume the reader
harn semantic service status               # inspect liveness, rolling calls, and usage
harn semantic service stop                 # finish the current call, then stop
harn semantic soak --minutes 60             # summarize a bounded live-reader window
harn semantic review prepare                # freeze the next bounded local review set
harn semantic review submit --file result.json
harn semantic doctor                       # check readers without a model call
harn semantic inspect <instance-or-generation>

once is the only command here that spends model calls. It projects safe evidence from active V3 generations, schedules the oldest eligible work, reuses an exact input cache, validates citations and privacy boundaries, and atomically publishes the resulting agent document.

The hard ceiling is 120 calls per coordination root in any rolling hour. A lower --calls-per-hour value is allowed. Requests beyond the active ceiling receive a deferred document with an eligible_after time.

The scheduler covers generations that have received no call in the current rolling hour before it refreshes an already-read generation. This keeps a busy or terminal generation from consuming the allowance while another card has no semantic reading.

service status reports rolling calls as used, limit, and available; the limit is still a call ceiling. The same response contains token usage for the current reader process and active rolling hour. It keeps native and estimated token maps separate, counts unreported calls, and groups calls and outcomes by source harness, configured model, resolved model, and model attestation. It also lists the three fixed harness routes, pending work, and the latest reader error. Invalid outcomes are grouped into bounded reason categories such as schema, citation, privacy, and unsupported_claim; rejected model text is not stored.

Live soak reports

harn semantic soak summarizes the last 60 minutes by default. Pass --minutes <count> to choose another whole-minute lookback. The command makes no model request. It reads the bounded semantic service log and reports:

• accepted, invalid, unavailable, and deferred outcomes;
• native, estimated, and unreported token usage with the existing model and harness breakdowns;
• controlled phase, expression, abstention, confidence, and harness counts;
• consecutive cue comparisons, changes, transition pairs, and rapid A-to-B-to-A reversals within 10 minutes; and
• how many passes contain expression instrumentation and whether the retained log covers the entire requested window.

Frequency means accepted model readings, not time displayed in Codec. A cue change can reflect a real work transition. A rapid reversal is a review candidate, not proof of flicker, and the report does not claim that an inference is correct without a labeled review.

Human inference review

Accepted readings also create short-lived local review candidates. The queue prefers phase or expression transitions, then expression-bearing readings, then the newest remaining readings. It freezes at most 12 candidates per study and does not make a model request.

Open /codec/review to compare bounded source facts with the accepted model reading. The page identifies the source harness, requested reader model, and model attestation. Answers use controlled labels for overall correctness, phase, expression, portrait helpfulness, transition quality, and confidence. There is no free-text field. The dashboard submits the completed frozen set through harn semantic review submit; the CLI remains the only write boundary.

Usage receipts

Every completed model call stores a typed usage receipt with its local call history and, when a semantic document came from that call, with the document. The receipt source is one of:

Source	Meaning
native	The local harness reported these token fields. Missing fields stay missing.
estimated	Harnery counted the visible semantic prompt and response with visible-o200k-base version 1.
unreported	The call has no usable native receipt and no complete visible response to estimate.

Claude Code currently reports input, output, cache-read, and cache-creation tokens. Codex reports input, cached input, cache-write input, output, and reasoning-output tokens from turn.completed. Cursor reports input, output, cache-read, and cache-write tokens in its terminal result. These fields are native harness telemetry; Harnery does not assume that every harness defines or reports a comparable total_tokens value.

The estimate is intentionally narrow. It covers only the prompt string Harnery passes to the harness and the visible final response. It does not include hidden harness instructions, provider-specific tokenization, cache behavior, reasoning tokens, or billable usage. Old calls without prompt and response measurements remain unreported; Harnery does not backfill them.

No current reader supplies authoritative billed cost. Claude Code’s total_cost_usd is a client-side estimate, so Harnery does not store it as native cost.

doctor reports which harness binaries are available, the configured model for each one, and the current semantic manifest. It makes no model request.

inspect accepts either an instance ID or generation ID and returns the current semantic document. Consumers decide whether a document is fresh by comparing its source cursor to the current V3 projection. Freshness is not stored as a second authority in the document.

harn web up and harn web start automatically start one detached semantic service for an active V3 coordination root. If startup fails, the dashboard still starts and Codec keeps its deterministic scene. Restarting the dashboard tries again. The service watches the canonical active-ledger path, debounces changes for five seconds, and consumes an incremental ledger cursor. Routine generation reads stay at least five minutes apart. Explicit attention, non-active lifecycle, and terminal evidence use a two-minute minimum interval.

Embedding hosts can call ensureSemanticServiceRunning from harnery/core/semantic before they launch the dashboard. The operation is idempotent and applies the same active-V3 and durable-pause checks as the Harnery CLI. If V3 changes genesis, the service resets its obsolete cursor, rebuilds the derived semantic state, and preserves the bounded rolling call and usage history.

service start still starts or resumes the reader before web startup. A stale process lease is recovered by the next automatic or explicit start. A durable stop marker keeps dashboard startup from restarting the reader until an explicit start clears it.

Stopping is graceful. An in-flight model request may finish, but no next request starts. The deterministic ledger, coordination commands, and Codec remain usable whether the service is stopped, unavailable, or recovering.

Codec

Codec reads validated agent documents on the server and presents them as a separate semantic channel. It can fill an otherwise inferred focus bubble and a neutral expression, but it never replaces event-backed activity, lifecycle, operation, attention, relationship, or freshness state. Expanded panel detail labels model synthesis and prediction, shows the reader, attestation, and usage provenance, and removes expired meaning while retaining a typed stale or unavailable receipt.

Version 2 adds an optional expression_cue. The reader may choose focused, curious, deliberating, investigating, building, coordinating, planning, verifying, weighing, or wrapping-up. It may also abstain. A cue must cite supplied events, use model-synthesis basis, and carry medium or low confidence. Deterministic expressions such as waits, blockers, errors, recovery, compaction, observation, context pressure, and open-subagent state always take precedence.

The structured-response schema binds each reply to the request’s exact generation ID, evidence digest, and event ID set. A reply for a different request or a fabricated citation is rejected before persistence.

The scene header reports whether the semantic service is running and how many rolling calls are in use. Opening its details panel shows routes, pending work, the latest error, native and estimated token totals, unreported calls, and per-harness/model breakdowns. Starting the dashboard authorizes recurring model calls under the same 120-call rolling ceiling as an explicit start. Codec remains read-only. Semantic documents and service health are local-only; presence relay payloads strip both.

Storage boundary

All state is disposable and rebuildable:

.harnery/semantic/v2/
├── manifest.json
├── agents/<generation_id>.json
├── cache/<cache_key>.json
├── service.json
└── service.log
.harnery/semantic/evaluations/meaning/
├── candidates/<candidate_id>.json
└── receipts/<receipt_id>.json

The cache key includes the evidence digest, source harness, configured and resolved model IDs, evidence contract version, and prompt contract version. Changing any of those inputs prevents stale reuse.

manifest.json keeps only the active rolling-hour call history. Each new call record contains numeric usage metadata and bounded invalid-reason categories, but never the raw prompt or model reply. service.json keeps the current process aggregate, and the bounded service log records per-pass usage totals plus controlled semantic-reading observations for soak reports. A reading retains an opaque subject fingerprint, model labels, phase, optional expression, and confidence. It excludes task text, model prose, event citations, instance IDs, and generation IDs. None of these files enters Event Ledger V3.

Review candidates retain bounded evidence values and the accepted reading for up to 7 days, with a maximum of 100 files. They exclude ledger event IDs, instance IDs, generation IDs, and raw model replies. Review receipts retain only opaque candidate IDs, controlled answers, corrections, model labels, and response timing for up to one year, with a maximum of 1,000 files. They do not retain task text, evidence text, or semantic prose.

Version 1 documents and cache entries are rebuildable derived state. The V2 reader does not migrate or consume them.