Skip to content

harness.lock

The lockfile records the stack that won, pinned and hashed, along with the evidence for choosing it. hlock resolve writes it. Don't edit it by hand, and do commit it.

Example

This is the lock from the Quickstart:

harness.lock
# This file is generated by harness-lock. Do not edit by hand.
lock-version = 1
generated-by = "harness-lock 0.1.2"
manifest-hash = "sha256:e6471474cb158117c727fbf3371e2287935d191f16c71c24c14ea80ca54693e2"

[stack]
name = "demo"
selection = "min-cost"

[[llm]]
role = "planner"
provider = "reference"
model = "qwen-7b"
resolved-from = "reference:qwen-7b"
fingerprint = "sha256:5aa2f4197dd24bf9889327f484ae9e7edbc8da533621923fbcae65e99f01bb86"

[decision]
kind = "none"

[harness]
name = "reference"
pattern = "single-agent"

[policy]
retries = 1
max-steps = 40
human-approval = "never"

[context]
isolation = "locked-only"

[evidence]
task-pack = "./tasks"
split = "search"
trials = 2

[evidence.success-rate]
mean = 1.0

[evidence.cost-usd-per-task]
mean = 0.0001

[evidence.latency-s-per-task]
p50 = 0.259
p95 = 0.395

[provenance]
backend = "local"

Empty tables and lists are omitted above for brevity. hlock show --json prints the complete file.

Top-level keys

Key Description
lock-version Schema version. This release reads and writes 1.
generated-by The harness-lock version that wrote the lock
manifest-hash Hash of the harness.toml the lock was resolved from. Used by hlock check.

Sections

Section Contents
[stack] Stack name, and the select rule that chose it
[[llm]] One entry per role: provider, model, the candidate string it came from, a fingerprint, and params
[decision] Decision model kind, its decisions, and thresholds
[harness] Harness name and pattern. For a harness with a profile, also the installed version, its install source (e.g. brew-cask:claude-code@2.1.285), and the adapter that ran the trials.
[policy] retries, max-steps, human-approval, risky-actions, tool-allowlist, sandbox
[context] Context isolation and compaction settings
tool, skill, instructions Locked peripherals (reserved in v0.1)
[evidence] The task pack and split measured, the trial count, and success-rate, cost, and latency statistics
[verify] Runtime verification thresholds: canary-tasks, min-success-rate, fingerprint-tolerance
[provenance] The backend that produced the lock, and the search settings

Pinned locks

hlock pin writes a lock with kind = "pin", no manifest-hash, and no evidence. Its [[llm]] entries may carry endpoint and runtime; [[tool]] entries for MCP servers carry transport, command, args, url, env, headers, scope and enabled; [[skill]] entries carry scope, path and vendored. It adds:

Section Contents
[[native]] Plugins, packages, extensions and marketplaces: kind (e.g. claude-code.plugin, pi.package), name, version, source, revision, integrity, enabled, config
[[runtime]] Inference runtimes: name, location (local or network), version, source, endpoint, and [[runtime.model]] entries with id, source, revision, digest, size-bytes, present
[[config]] Harness config files: id, path, format, restore (whole, pointers, record), pointers, digest, vendored
[[secret]] Placeholders that replaced secrets: name (the environment variable that supplies it) and used-by

Localized locks

hlock localize writes a lock with kind = "localized", base-lock naming the source lock, local [[llm]]/[[runtime]] entries, [[config]] entries that point the harness at the local endpoint, and a [localize] table recording what was replaced, the candidates considered, the memory budget, whether it was evaluated, and the source lock's evidence as a baseline.

harness.opt.lock

hlock optimize writes a separate opt-lock with the same shape, plus what the optimizer produced: the chosen hyperparameters, applied prompts, fine-tune adapters, the data split, and the budget, all content-addressed. Adopt it into harness.lock with hlock optimize --apply.

harness.lock.prev

hlock upgrade --apply saves the previous lock here so hlock upgrade --rollback can restore it. You can commit it or ignore it.