Migrating to 1.0

HAR 1.0 moves the harness machinery out of .har/ and into the package. A pre-1.0 harness carries ~20 vendored files; a 1.0 harness keeps only what is yours — config, stages, hooks, plugins, docs. CLI and MCP are the only entry points: har env launch 1, har env verify 1 --full, and the MCP tools.

What changed in the release, in short: HAR 1.0.0.

Nothing breaks on upgrade day

Upgrading @osfactory/har does not brick an old harness. Pre-1.0 vendored scripts keep working against the 1.0 CLI for a compatibility window — you get loud deprecation warnings, not breakage. Migrate when ready.

Run the migration

har env maintain

maintain detects the pre-1.0 shape (vendored runtime scripts, shell functions in harness.env, legacy port triplets) and drives a versioned migration:

1. Mechanical steps run as code. Every installed file is classified using the manifest checksums:

   • Stock (never edited) — replaced silently: lifecycle wrappers are deleted, harness.env boilerplate becomes schema’d config.
   • Adapted (you edited it) — nothing is overwritten; the customization is lifted into the contract or handed to you in the prompt. Machinery still sourced by a surviving script (e.g. a stage script that sources agent-slot.sh) is retained until you rewrite that script against the 1.0 stage surface — the prompt tells you where.

2. A MIGRATE-PROMPT.md is generated (same pattern as ADAPT-PROMPT.md) covering only the non-mechanical residue: which adapted files carry real customization, where each one lands in the new model (config value, registered stage, hook, or local plugin), and a verification checklist. Run it with your coding agent.

3. Finish green:

   har env doctor
   har env launch 1 && har env verify 1 --full

4. Finalize. Record the migration and clean up the transient artifacts (.har/migrate/, the prompt):

   har env maintain --finalize --summary "Migrated to the 1.0 config surface"

Where old customizations go

Pre-1.0 customization	1.0 home
Edited values/exports in harness.env	Schema’d config keys in harness.env
Shell functions in harness.env	Removed — provided by the runtime
Patched verify.sh steps	Registered stages in stages.json / .har/stages/
add-stage --custom scripts	Local plugins or plain command stages
Patched launch.sh/teardown.sh side effects	Lifecycle hooks in .har/hooks/
Deep runtime patches	har env eject — keep script ownership explicitly

If the harness is heavily customized and not worth lifting yet, the migration offers eject: you keep working scripts and full ownership, and can adopt the packaged runtime later.

What 1.0 deliberately does not break

• har env … commands and MCP tool contracts.
• stages.json stage entries (lifecycle stages dispatch by kind) and existing slot registries.

What it does retire: vendored-script internals, add-stage --custom, harness.env shell functions, and single-signal drift (see two-signal drift).

What a migrated harness looks like

har env maintain --migrate finishes the mechanical half. Use this inventory to confirm the result, and to spot the leftovers it cannot decide for you.

Should be gone — the runtime now lives in the package:

.har/agent-slot.sh          .har/lib/infra.sh
.har/provision-toolchain.sh .har/lib/node-pm.sh
.har/simulator.sh

Should be gone — lifecycle wrappers are not an entry point:

.har/launch.sh   .har/verify.sh    .har/teardown.sh
.har/preflight.sh .har/agent-cli.sh .har/setup-infra.sh
.har/attach.sh

Should be yours — harness.env, stages.json, stages/, hooks/, plugins/, env.template, ecosystem.agent.template.cjs, docker-compose.agent.yml, and the docs.

Confirm all of it in one step:

har env doctor

Doctor fails if any surviving script still loads retired machinery — the exact trap described below.

Check your own scripts for retired machinery

The migration deletes the vendored runtime, so any script of yours that still sources it breaks the moment someone runs it. This bit us: HAR’s own control/.har/attach.sh shipped through the 1.0 migration still doing source "$SCRIPT_DIR/agent-slot.sh" after the migration had deleted that file.

grep -rn 'agent-slot\.sh\|provision-toolchain\.sh\|simulator\.sh\|lib/infra\.sh\|lib/node-pm\.sh' .har/

Anything that turns up needs rewriting against the 1.0 stage surface. You rarely need what you were sourcing: stage scripts and hooks already receive WORK_DIR, ENV_FILE, AGENT_ID, and HAR_HARNESS_DIR in the environment, and the slot’s env file is sourced for you.

Docs are not migrated for you

The migration rewrites scripts and config; it does not rewrite prose. Re-read your own .har/README.md and any repo-level AGENTS.md, and fix anything that still describes the pre-1.0 world — file tables listing deleted machinery, and especially the old claim that ./.har/*.sh is an entry point. CLI and MCP write the same run and validation records; the commit gate is satisfiable from either surface. Agents read these files as instructions; a stale table sends them down a path that no longer exists.

Keep a stale global har from fighting your harness

If the har on PATH is older than the version your harness pins, upgrade it — npm i -g @osfactory/har@latest, or npm i -D @osfactory/har in the repo. In CI, install or build the runtime and put it on PATH before invoking har env …; otherwise you are testing against whatever npx @osfactory/har@<pinned> resolves to rather than the version you meant.