LHT settings

LHT (Long-Horizon Task harness) keeps Code sessions on track after the model produces a plan or checklist: nudges to continue, completion gates before finishing, and an optional CRAFT macro review loop for large refactors.

Office mode does not use LHT. Sidebar Settings → LHT settings appears only in Code sessions.

Since v0.8.6, prefer portable success criteria via Gate-as-Code (shared predicate library with night queue and skill stage gates). Presets long-refactor / long-fix write product verify gates in enforce mode; toolchain verify shows a live “running” status.

Open the panel

Sidebar → Settings → LHT settings.

The intro line states that values persist to ~/.zagens/config.toml under [long_horizon], separate from the composer chip (below).

Two control surfaces: who wins

LHT behavior comes from the composer chip (per turn) and the LHT settings panel (persistent). For the active turn, the composer wins.

flowchart TD
  A[Send message] --> B{Composer chip}
  B -->|LHT·off| C[Harness hard-disabled this turn<br/>Enable + Default mode ignored]
  B -->|LHT·strict| D[Plan-first + enforce sub-gates<br/>Overrides Default mode below]
  B -->|LHT auto| E[Read long_horizon from config.toml]
  E --> F[Nudges + gates after plan/checklist exists]

Composer tri-state

Hover tooltips explain each state; click cycles auto → strict → off → auto.

Panel banner (composer override)

Save and presets

① Harness presets

Four cards map to one-click config.toml overlays (custom completion_gate lists kept).

Large refactor + macro loop: preset enables macro loop, but the UI requires composer LHT·strict or Default mode Strict below — otherwise macro fields stay disabled.

reinject_every_steps is preset-only today; no panel slider — edit config.toml to tune.

② Long-horizon harness

Panel section Long-horizon harness.

Enable LHT harness

• Meaning: Once a plan / checklist exists, enable continue nudges and completion constraints.
• Default: on (general coding preset).
• Disabled when: composer is LHT·off.

Default mode

• Default: auto.
• Disabled when: composer is LHT·off or LHT·strict (strict chip already sets mode).

Git progress signal

• Meaning: Git working-tree changes between nudges count as qualified progress.
• Default: on.
• Tip: keep on inside git repos; optional off for non-git folders.

Max nudges per checklist item

• Meaning: How many times the runtime nudges a single checklist item.
• Range: 1–20 · default 5.

Blocked nudges without progress

• Meaning: After this many nudges without qualified progress, LHT marks the turn blocked (composer may show “LHT paused”).
• Range: 1–10 · default 3.

Auto-continue after gate gives up (experimental)

• Meaning: When completion gates exhaust retries but the task graph is incomplete, reset nudge counts and keep the turn alive.
• Default: off.
• Sub-field — Max auto-continue rounds per turn: shown only when enabled · range 1–64 · default 16.

③ Completion gate (task-agnostic)

Panel section Completion gate (task-agnostic). Three gates apply to all code tasks — no per-repo panel setup.

Recommended path: Off / Observe first → Enforce when your team is ready.

The three gates

Each gate:

• Stub gate default: Observe (other gates default off unless your config differs).

Round and failure limits

Custom verify / deliverable rows

If you hand-wrote in config.toml:

[[long_horizon.completion_gate.verify]]
# ...

[[long_horizon.completion_gate.deliverable]]
# ...

The panel does not edit them but preserves them on save. A amber hint appears when counts are non-zero — edit the file directly.

④ Macro review loop (experimental)

Panel section Macro review loop (experimental). Under LHT strict, optionally inserts a CRAFT review segment:

Implement → CRAFT sub-agent review (gap list) → update checklist → main agent remediation → …

Requirements (both):

1. Enable macro review loop checked below, and
2. Composer LHT·strict or Default mode Strict

Otherwise fields are disabled with: macro loop is available only in strict mode.

Enabling shows a cost warning: extra review sub-agents — higher token use and API cost than LHT alone.

Enable macro review loop

• Default: off (large refactor preset turns it on).

Enter CRAFT when

• Large refactor preset default: when checklist complete.

Remediation keeps fixing CRAFT gaps; micro gates must still pass to finish.

Cycles and small tasks

config.toml field map

Main keys the panel writes (for hand-editing):

[long_horizon]
enabled = true
mode = "auto"          # "auto" | "strict"
progress_via_git = true
max_nudges_per_item = 5
blocked_nudges_without_progress = 3
reinject_every_steps = 0   # preset / manual only — no panel control
auto_continue = false
max_auto_continue_rounds = 16

[long_horizon.completion_gate]
auto_verify_replay = "off"   # off | observe | enforce
toolchain_gate = "off"
stub_gate = "observe"
max_manifest_rounds = 5
max_audit_rounds = 5
max_infra_strikes = 3

[long_horizon.macro_loop]
enabled = false
auto_enter_craft = "user_confirm"
max_macro_cycles = 3
max_craft_rounds_per_cycle = 2
craft_on_small_tasks = false
min_checklist_items_for_craft = 3

Composer chip writes ~/.zagens/settings.toml:

lht_composer_mode = "auto"   # auto | strict | off

Recommended workflows

Watch progress in the UI

FAQ

Changed the panel but this turn didn’t change?
Composer overrides the active turn; you may need Save and (if streaming) sidecar restart. Chip tri-state applies on the next turn.

LHT·off vs craft-audit preset?
Off disables harness for one turn; craft-audit persistently sets enabled=false and pairs with scratchpad workflow.

Enforce gates won’t let the turn finish?
Expected. Switch gates to Observe, set composer LHT·off, or fix failing verify / stub / build items.

Macro loop enabled but no CRAFT?
Check strict mode, small-task threshold, and whether enter timing is manual-only.

Related: LHT overview · CRAFT · Execution policy · Context usage