harness-setup

name	harness-setup
description	Use when installing, updating, auditing, or uninstalling The Last Harness isolated Pi package or one-line installer. Covers the tlh wrapper, isolated Pi profile, settings merges, and rollback documentation.

Harness Setup

Use this workflow when changing this repository's Pi package, one-line installer, isolated tlh wrapper, or persistent settings behavior.

Checklist

1. Keep upstream Pi as the runtime unless the user explicitly asks for a forked/rebranded binary.
2. Keep The Last Harness isolated from normal Pi:
   • normal Pi uses ~/.pi/agent
   • tlh uses ~/.the-last-harness/agent by default
   • installer Pi commands must set PI_CODING_AGENT_DIR to the isolated agent dir
3. Keep the installer split clear: install.sh is the stage-0 Bash bootstrapper that finds/fetches support files, while scripts/tlh-install.mjs is the stage-1 Node helper that runs the normal install flow. Keep their support-file manifests aligned.
4. Put shareable Pi resources in package directories:
   • extensions/
   • skills/
   • prompts/
   • themes/
5. Put installer-owned default settings in config/settings.defaults.json and bundled default extension metadata in config/default-extensions.json.
6. Merge settings conservatively into the isolated settings file only:
   • append missing packages entries
   • respect persistent tlh.disabledDefaultExtensions opt-outs
   • preserve existing isolated user values by default
   • require --force before overwriting scalar values
   • back up existing isolated settings before writing
7. Keep the installer idempotent. Running it twice should not duplicate package entries or clobber user settings.
8. Document every persistent change and the uninstall path.

Validation

Before release, run:

npm run validate

The aggregate validation script runs installer smoke checks, npm test, npm run lint, the settings merge dry-run, and npm pack --dry-run. The smoke script includes syntax checks for stage-0, stage-1, helper CLIs, and scripts/lib/, plus a manifest check that keeps the bootstrapper aligned with the stage-1 support manifest.

For install behavior, test with temporary isolated paths:

agent_dir="$(mktemp -d)/agent"
bin_dir="$(mktemp -d)"
bash install.sh --dry-run --agent-dir "$agent_dir" --bin-dir "$bin_dir"

Verify dry runs do not write:

test ! -e "$agent_dir/settings.json"
test ! -e "$bin_dir/tlh"

Rollback guidance

Tell users they can remove the isolated wrapper and profile with:

rm -f ~/.local/bin/tlh
rm -rf ~/.the-last-harness

Normal ~/.pi/agent settings are intentionally not modified by this installer.