Harness Migration

Harness Migration

First confirm a broken harness/ ledger actually has a generation mismatch rather than some other fault. If it does, replay it into a freshly initialized current-format repository; the source is never written to. Replay is the only supported migration path — there is no in-place repair tool.

This skill assumes nothing is installed. It fetches the current source into a throwaway directory and runs everything from there. A Harness installation already on the machine — including a running daemon — is left untouched.

Before anything: confirm this is the right document

This skill is versioned in the harness-anything repository as skills/harness-migration/SKILL.md on main, and that branch is the authority. Read it from a git ref, never from whatever working tree happens to be at hand — a checkout parked on another branch may not carry this file at all, or may carry an older revision, and neither difference is visible once the text is in front of you.

git -C <any-checkout-of-harness-anything> show origin/main:skills/harness-migration/SKILL.md

A machine may also carry a separately maintained skill with a similar name — harness-ledger-migration is the one that exists today, and it is an older, different document rather than an alias. Following it instead is a silent wrong turn. The front matter settles it: this skill's name: is exactly harness-migration.

The one rule that makes this work

Every command runs against an isolated daemon user root. Export it once and keep it exported for the whole session:

export HARNESS_MIGRATION_WORK="$(cd "$(mktemp -d "${TMPDIR:-/tmp}/ha-migration.XXXXXX")" && pwd -P)"
export HARNESS_DAEMON_USER_ROOT="$HARNESS_MIGRATION_WORK/daemon-user-root"
mkdir -p "$HARNESS_DAEMON_USER_ROOT"

Without it, the CLI connects to whatever Harness daemon is already running on the machine and that daemon serves a different generation of the code. The failure does not announce itself as a conflict — it arrives as:

error code=missing_vertical

with "origin":"daemon" in the JSON receipt. Match on those two fields, not on the hint text: the hint describes an unavailable vertical, which is true but misleading, and it reads differently depending on which generation the running daemon serves. code=missing_vertical together with "origin":"daemon" means HARNESS_DAEMON_USER_ROOT is not set.

Do not stop or uninstall the user's existing Harness to work around it: isolation is sufficient, and stopping their daemon interrupts work you are not responsible for restoring.

The cd … && pwd -P wrapper around mktemp is what keeps the path readable. On macOS $TMPDIR already ends in a slash, so the template produces a doubled slash, and /tmp is itself a symlink into /private/tmp. Either way the raw path turns up in every receipt from here on and does not match what you see on the filesystem. pwd -P resolves both, once, at the start. Quoting is not involved: "${TMPDIR:-/tmp}"/ha-migration.XXXXXX and "${TMPDIR:-/tmp}/ha-migration.XXXXXX" are the same string to the shell, and neither one avoids the doubled slash.

If your shell does not persist between commands

The steps below accumulate exported variables and, in step 1, a shell function. An agent that gets a fresh shell per tool call keeps none of them — the second command runs with HARNESS_DAEMON_USER_ROOT unset and connects to the machine's own daemon, which is exactly the failure this section exists to prevent. This is the root cause of the downstream traps the later steps describe individually (zsh word-splitting in step 1, nohup not seeing the function in step 8, env resolving ha from PATH in step 9).

Write the session state to a file and source it at the start of every later command:

export HARNESS_MIGRATION_ENV="$HARNESS_MIGRATION_WORK/env.sh"
cat > "$HARNESS_MIGRATION_ENV" <<EOF
export HARNESS_MIGRATION_WORK='$HARNESS_MIGRATION_WORK'
export HARNESS_MIGRATION_ENV='$HARNESS_MIGRATION_ENV'
export HARNESS_DAEMON_USER_ROOT='$HARNESS_DAEMON_USER_ROOT'
EOF
# every later command:  . "$HARNESS_MIGRATION_ENV" && <command>

Append each new export to that file as the steps below introduce it — HA_ENTRY, ARCHIVE_SOURCE, WORK_SOURCE, TARGET_REPO, DRY_RUN, LEDGER_ARCHIVE, SOURCE_SHA_BEFORE. Record $HARNESS_MIGRATION_ENV somewhere you will still have it later; it is the one path you must not lose.

Keep this file inside $HARNESS_MIGRATION_WORK, and if you write anything anywhere else, put the repository name in its filename. mktemp already makes the work directory unique, but agents habitually drop scratch files into a shared session scratchpad instead — and env.sh, dry-run.txt and apply.log are the same name in every migration. When two migrations run in parallel, a sibling overwriting your env file is not hypothetical: it has happened, and it presents as your own variables quietly turning into someone else's, several steps after the damage. Either keep everything under $HARNESS_MIGRATION_WORK, or name it env-<repo>.sh, dry-run-<repo>.txt, apply-<repo>.log.

1. Fetch the current source

Node 24 or newer is required. Check before cloning:

node --version

The CLI is run from its TypeScript entry point, which relies on Node's native type stripping. On an older Node every command fails with

TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".ts"

which reads like a missing build step and is not one — no amount of npm run build fixes it. Stop and tell the user to upgrade Node; nothing below works until they do.

cd "$HARNESS_MIGRATION_WORK"
git clone --depth 1 https://github.com/FairladyZ625/harness-anything.git ha-src
cd ha-src
npm install --no-audit --no-fund
export HA_ENTRY="$HARNESS_MIGRATION_WORK/ha-src/packages/cli/src/index.ts"
ha() { node "$HA_ENTRY" "$@"; }
ha --version

Expect a version line. The repository is about 10 MB and install takes seconds.

ha here is a shell function, not an exported variable. The obvious export HA="node …/index.ts" followed by $HA --version works in bash and silently fails in zsh, which does not word-split unquoted parameters: zsh passes node …/index.ts as a single argument and the receipt comes back unsupported_command. A function behaves identically in both shells.

If your shell does not persist between commands, append both the variable and the function to the env file from the top of this skill, and source it every time:

{ echo "export HA_ENTRY='$HA_ENTRY'"
  echo 'ha() { node "$HA_ENTRY" "$@"; }'; } >> "$HARNESS_MIGRATION_ENV"

Two consequences worth knowing now rather than at step 8:

• The function lives in the shell that defined it. Anything that runs in a detached process — see step 8 — must spell out node "$HA_ENTRY" … instead, and sourcing the env file does not change that.
• env -u HARNESS_DAEMON_USER_ROOT ha …, which step 9 uses on purpose, does not see the function. env execs a program, so it resolves ha from PATH — the machine's own installation. That is exactly what step 9 wants, and step 9 says so again where it matters.

Do not look for node_modules/.bin/ha. The published bin points at dist/, which a source checkout does not contain, so the linked binary is absent. Running the TypeScript entry directly is the supported path here and needs no build step.

1a. Confirm the symptom is a ledger-generation mismatch before importing

Do this after step 1 fetches the current source, before creating a destination or running migrate import. The symptoms below are an entry point, not a decision: both kinds of ledger can produce them.

Set the source path once. The scan only reads its event files; it does not need the daemon and does not alter the source.

export ARCHIVE_SOURCE="$(cd /absolute/path/to/repository-with-harness && pwd -P)"
export CANONICAL_EVENT_CONTRACT="file://$HARNESS_MIGRATION_WORK/ha-src/packages/kernel/src/domain/doc-sync.contract.ts"
node --input-type=module - "$ARCHIVE_SOURCE/harness/events" "$CANONICAL_EVENT_CONTRACT" <<'NODE'
import { readdir, readFile } from 'node:fs/promises';
import { join } from 'node:path';

const [eventsRoot, contractUrl] = process.argv.slice(2);
const { parseCanonicalEvent } = await import(contractUrl);
const counts = { files: 0, parsed: 0, unknown_schema: 0, legacy_cut_shape: 0, other: 0 };
async function* eventFiles(dir) {
  for (const entry of await readdir(dir, { withFileTypes: true })) {
    const file = join(dir, entry.name);
    if (entry.isDirectory()) yield* eventFiles(file);
    else if (entry.isFile() && entry.name.endsWith('.json') && entry.name !== 'head.json') yield file;
  }
}
function hasLegacyCut(value) {
  if (!value || typeof value !== 'object') return false;
  if (Array.isArray(value)) return value.some(hasLegacyCut);
  const cut = value.baseLedgerSha;
  if (cut && typeof cut === 'object' && !Array.isArray(cut)) {
    const keys = Object.keys(cut).sort();
    if (keys.length === 2 && keys[0] === 'repoId' && keys[1] === 'sha') return true;
  }
  return Object.values(value).some(hasLegacyCut);
}
for await (const file of eventFiles(eventsRoot)) {
  counts.files++;
  let text, event;
  try {
    text = await readFile(file, 'utf8');
    event = JSON.parse(text);
    parseCanonicalEvent(text);
    counts.parsed++;
  } catch (error) {
    const message = error instanceof Error ? error.message : String(error);
    if (message === 'canonical event schema is unknown') counts.unknown_schema++;
    else if (message === 'doc event envelope or payload is invalid' && event?.schema === 'doc-event/v1' && hasLegacyCut(event)) counts.legacy_cut_shape++;
    else counts.other++;
  }
}
console.log(JSON.stringify(counts, null, 2));
NODE

Interpret the counts conservatively:

• If unknown_schema > 0 or other > 0, this is a previous-generation ledger rather than the narrow S4-only cut mismatch. Continue with the replay steps in this skill. The replay importer constructs current migration events rather than copying source event bytes.

• If legacy_cut_shape > 0, unknown_schema = 0, and other = 0, the ledger is a current-generation ledger whose doc cuts predate S4. Replay handles it, and replay is the only supported path: there is no in-place restamp migration, and none is planned. An in-place restamp was built and evaluated; it was deliberately not shipped, because a tool that rewrites cut identity in place has to be trusted on a ledger nobody can re-derive, while replay reconstructs the destination from source events and leaves the source untouched.

  Know what replay costs you here: it remaps entity IDs and writes a new ledger, which is more than this ledger strictly needs — only its cut identity is stale. Budget for the ID remapping (see the ID mapping steps below) rather than looking for a narrower tool. If remapped IDs are genuinely unacceptable for your ledger, stop and report that; do not improvise a hand-edit of event bytes.

• If all three failure counts are zero, the stream already parses under the current code. This is not a generation mismatch, so migration will not fix it; stop and investigate the reported symptom separately.

If the scan itself cannot read the events directory or run the current parser, stop and report that failure. Do not infer the generation from harness.yaml: both generations can carry schema: harness-anything/v1.

2. Freeze and back up the source ledger

Back up and digest harness/ only — never the repository root.

export WORK_SOURCE="$HARNESS_MIGRATION_WORK/legacy-copy"
mkdir -p "$HARNESS_MIGRATION_WORK/backups" "$WORK_SOURCE"
export LEDGER_ARCHIVE="$HARNESS_MIGRATION_WORK/backups/legacy-harness.tar"
COPYFILE_DISABLE=1 tar -cf "$LEDGER_ARCHIVE" -C "$ARCHIVE_SOURCE" harness
export SOURCE_SHA_BEFORE="$(COPYFILE_DISABLE=1 tar -cf - --exclude='harness/.git' -C "$ARCHIVE_SOURCE" harness | shasum -a 256 | awk '{print $1}')"
printf 'source-before %s\n' "$SOURCE_SHA_BEFORE"
tar -xf "$LEDGER_ARCHIVE" -C "$WORK_SOURCE"

$WORK_SOURCE now contains harness/ and nothing else, which is all the importer reads — --source takes the repository root and descends into harness/ itself.

Three things this deliberately does not do, each for a reason worth knowing:

• No git bundle. harness/ is its own git repository and the outer repo ignores it (/harness/ in .gitignore, git ls-files harness/ returns nothing). A bundle of the outer repo therefore contains zero ledger content — it looks like a backup and protects nothing.
• No repository-root digest. The root contains .harness/, which is ignored runtime state — locks, write-journal, cache, script-runs, task-holders — that any running daemon rewrites continuously. A root digest changes on its own between the before and after reads, so the "source untouched" check would report a false failure every time. A check that must be ignored to proceed is worse than no check.
• No cp -a of the root. It copies node_modules and the whole .git directory, which the importer never reads.

The digest excludes harness/.git for the same reason the root digest is excluded entirely: it is live metadata, not content. A git fetch from any mirror or a background maintenance run rewrites packed-refs, FETCH_HEAD and the reflog without touching a single ledger file, and the closing comparison then fails for a reason unrelated to the importer. This bit a real migration — an unrelated mirror fetch landed mid-run and the source looked modified when it was not. The archive is not filtered: a backup must carry the ledger's own git history, and only the digest needs the exclusion.

The digest and the tar print nothing while they run. On a small ledger they are effectively instant — about a second each for a 963-event, 257 MB harness/ — so if you are staring at a blank prompt for more than a few seconds, look at the size of what you are digesting rather than waiting. Only a genuinely large ledger takes tens of seconds. Either way, if it runs for many minutes you are digesting more than harness/; check the -C argument. Nothing may write to $ARCHIVE_SOURCE/harness/ while the migration runs, or the closing digest will differ for a reason that has nothing to do with the importer.

Show the user $LEDGER_ARCHIVE and stop until they confirm one independent copy exists off this machine. Migration is one-shot; this is the only point where that confirmation is cheap.

If you are a dispatched agent with no way to reach the user, you cannot satisfy that stop — say so rather than pretending you did. Record the archive path and its size, state plainly in your report that the off-machine copy was never confirmed, and continue. The rest of the migration writes only to $HARNESS_MIGRATION_WORK, so nothing before step 9 can lose the source; step 9 is where the missing confirmation actually matters. Only the confirmation is waived, not step 9. Unless your dispatch says otherwise, landing the ledger and running the six landing checks are yours to do; carry the unconfirmed backup forward as a stated caveat in your report instead of treating it as permission to stop at step 8.

Every repair below targets $WORK_SOURCE. $ARCHIVE_SOURCE is read-only and its harness/ digest is re-checked at the end.

3. Initialize the destination

Ask the user for the new repository id, owner person id, and display name.

export TARGET_REPO="$HARNESS_MIGRATION_WORK/new-repository"
mkdir -p "$TARGET_REPO" && cd "$TARGET_REPO"
git init -q . && git commit -q --allow-empty -m "base"
ha init --repo-id <new-repo-id> --person-id <owner-person-id> --display-name '<display-name>'

Expect a receipt listing created paths and a commit sha. The first command in a fresh user root starts an isolated daemon on its own; that is expected and it belongs to this migration, not to the user's installation.

If init fails, move this directory aside and start a new empty one. Do not repair a half-initialized target in place.

4. Dry-run and read the output

export DRY_RUN="$HARNESS_MIGRATION_WORK/dry-run.txt"
ha migrate import --source "$WORK_SOURCE" --dry-run > "$DRY_RUN" 2>&1; echo "exit=$?"
cat "$DRY_RUN"

Use the importer as the classifier. Do not inventory the old repository or invent categories of your own. Act only on what the report prints:

• Oracle: same-cut-projection or Oracle: rebuilt-source
• five reconciliation rows (task / decision / fact / relation / execution)
• Format observations and each ACCEPT or SKIP line
• Attribution
• the authored coverage table and each required row
• Authored reconciliation

Do not manufacture .harness/cache/task.sqlite in the working source. If it is absent, the importer rebuilds a disposable read-only oracle from committed flat or sharded events and older authored packages. Oracle: rebuilt-source is the expected receipt for that path; the source tree and Git refs must remain byte-for-byte unchanged.

Branch on those rows:

5. Resolve destination conflicts — one batch, one decision

ha init seeds README, ADR, milestone, walls and people.yaml files. A source ledger usually has its own versions of those paths. Each conflict row prints both sides and the exact flag to use:

| people.yaml | required | 1 | FAIL | destination content differs:
  source kind=file, source sha256=240b9a55…, source bytes=561;
  destination kind=file, destination sha256=39e0af13…, destination bytes=512;
  resolve with --resolve harness/people.yaml=destination|source |

Handle every conflict in one pass. Never ask about them one at a time — a migration has a handful of these and each round trip costs the user an interruption for a decision that is usually the same one.

Read both sides of all of them first:

CONFLICTS=($(grep -o -- '--resolve [^=]*=' "$DRY_RUN" | sed 's/--resolve //;s/=$//' | sort -u))
printf 'conflicts: %s\n' "${#CONFLICTS[@]}"
for c in "${CONFLICTS[@]}"; do
  printf '\n===== %s :: DESTINATION =====\n' "$c"; cat "$TARGET_REPO/$c" 2>/dev/null
  printf '\n===== %s :: SOURCE =====\n' "$c"; cat "$WORK_SOURCE/$c" 2>/dev/null
done

The default is destination for every row. The destination file is the current format's skeleton and the migration exists to adopt it — a source file that merely says the same thing in the old shape has nothing to preserve.

What the source file may have is project-specific substance the skeleton does not carry: local conventions, routing rules, directory contracts, a project's own standards. Carry that content forward into the destination file. Merging is an edit you make, not something the importer does; the flag is still =destination.

So present one table and ask for one confirmation:

Say plainly: this is the default, and they can override any row to source if they want the old file kept verbatim. One answer covers the whole table.

people.yaml is normally automatic. Compatible rosters are unioned through the same People Action transition and published as people-event/v1; the destination owner binding remains and source-only people, roles, credentials, and non-conflicting scalar details carry forward. No question or hand edit is needed.

Only a genuine scalar or role-authority contradiction produces a required row. For that row, ask which side to retain with the explicit flag and record the losing declaration in the hand-over. After migration, reconcile individual entries only through ha people add, ha people set-role, and ha people remove; never commit a manual edit to the ledger.

Do the merge edits after the final apply in step 8, not now. Step 8 recreates the destination from scratch, which would discard anything edited earlier. Record the third column now; apply it once at the end.

Collect the answers into repeated flags and re-run:

export RESOLVE_ARGS=(
  --resolve 'harness/context/README.md=destination'
  --resolve 'harness/people.yaml=source'
)
ha migrate import --source "$WORK_SOURCE" "${RESOLVE_ARGS[@]}" --dry-run > "$DRY_RUN" 2>&1; echo "exit=$?"

Each answer comes back as a row beginning resolved: destination or resolved: source, carrying both digests so the discarded side stays visible. A conflict left out of the flags stays required.

A directory target accepts only =destination. If =source reports that the target is a directory, show the error and have the user handle that path.

6. Rebuild legacy presets as v3 packages

Legacy preset packages are not carried over — they are rebuilt against the current format.

find "$WORK_SOURCE/harness/presets" -mindepth 1 -maxdepth 1 -type d | sort
ha preset inspect standard-task --profile baseline --vertical software/coding --locale en-US --json

The legacy-migration preset bundled with the current release documents the exact v2 → v3 field mapping. Read it:

cat "$HARNESS_MIGRATION_WORK/ha-src/packages/preset/assets/software-coding/presets/legacy-migration/PRESET.md"

Build each replacement under $HARNESS_MIGRATION_WORK/rebuilt-presets/<id>/, then validate and install from the destination:

cd "$TARGET_REPO"
for NEW_PRESET in "$HARNESS_MIGRATION_WORK/rebuilt-presets"/*; do
  ha preset validate --source "$NEW_PRESET" --json
  ha preset install --source "$NEW_PRESET" --json
done
ha preset audit --vertical software/coding --json

Continue only when every validation reports "valid": true and the audit shows no blocked package.

preset audit --json answers about the vertical as a whole — a count of packages and a count of issues — not one row per package. So it tells you whether something is blocked, not which package it is. The per-package verdict is the validate output in the loop above; if the audit reports issues, read back the validations rather than looking for a package list in the audit receipt that is not there.

Then take the old packages out of the copy being imported — the archived original still has them:

mv "$WORK_SOURCE/harness/presets" "$HARNESS_MIGRATION_WORK/legacy-presets-rebuilt"

Re-run the dry-run from section 4 with "${RESOLVE_ARGS[@]}". The presets/** row must be gone.

7. Handle historical-format observations

grep -E '^- (ACCEPT|SKIP) ' "$DRY_RUN"

Show every observation to the user. SKIP rows are legacy-parser diagnostics; they are not subtracted from the projection oracle and do not independently block a reconciled import.

ACCEPT schedule_definition_facet_mismatch with treatment=accepted_truth_gap is the one known schedule declaration-claim variant. The disposable oracle uses the definition facet from the event while the original claim blob stays untouched in the forensic archive. Confirm the warning has that exact code and treatment, then continue; do not rewrite it.

For unsupported_legacy_event, preserve the source and collect the exact event path, schema, and nested parser error. For migration_projection_rebuild_failed, collect the nested cause and identify any missing or corrupt committed blob. Stop and report either case as a missing compatibility fixture. Do not hand-edit canonical event bytes to get past it. A migration_projection_oracle_cut_mismatch means source writers were not frozen or a local projection is stale: stop the writers, remove or regenerate that local cache, and dry-run again.

If a dry-run reports reconciliation FAIL or invalid_write_plan, do not apply. Keep the full receipt and report the named kind/event. Apply is allowed only after dry-run exits zero and proves every planned event against the current write contract.

8. Recreate the destination, then apply once

Source repairs must be replayed into a target that never saw the broken data.

cd "$HARNESS_MIGRATION_WORK"
mv "$TARGET_REPO" "$HARNESS_MIGRATION_WORK/preview-repository"
mkdir -p "$TARGET_REPO" && cd "$TARGET_REPO"
git init -q . && git commit -q --allow-empty -m "base"
ha init --repo-id <new-repo-id> --person-id <owner-person-id> --display-name '<display-name>'
for NEW_PRESET in "$HARNESS_MIGRATION_WORK/rebuilt-presets"/*; do ha preset install --source "$NEW_PRESET" --json; done
ha migrate import --source "$WORK_SOURCE" "${RESOLVE_ARGS[@]}" --dry-run; echo "exit=$?"

Apply only when that exits zero, all five reconciliation rows pass, authored coverage has no required, and every accepted historical observation has been reviewed. A source rebuilt without task.sqlite must say Oracle: rebuilt-source.

Run apply detached, and poll it. It prints nothing at all until it finishes, so a foreground run is indistinguishable from a hang and any caller with a command timeout will kill it partway. That has already happened once: an agent harness terminated a real apply at around the 60-minute mark, and a half-imported target is not recoverable — step 8 has to start over from ha init.

Budget from the event count, not from the worst case. Apply costs roughly 200 ms per event and scales with the count, not with the byte size: a 963-event / 257 MB ledger finished in 211 seconds, while a 21,000-event ledger took 1h22m. Multiply before you plan around it; treating every migration as an overnight job over-provisions a small one by more than an order of magnitude.

Have the detached run record its own exit code. A background process that has already been reaped cannot be asked for its status from another shell — and "apply exited zero" is a line in the "Done when" list, so an unrecoverable exit code means the migration cannot be signed off. Write it to a file as the process ends:

cat > "$HARNESS_MIGRATION_WORK/apply.sh" <<'EOF'
#!/bin/sh
node "$HA_ENTRY" migrate import --source "$WORK_SOURCE" "$@"
echo "exit=$?" > "$HARNESS_MIGRATION_WORK/apply-exit.txt"
EOF
chmod +x "$HARNESS_MIGRATION_WORK/apply.sh"

cd "$TARGET_REPO"
nohup "$HARNESS_MIGRATION_WORK/apply.sh" "${RESOLVE_ARGS[@]}" \
  > "$HARNESS_MIGRATION_WORK/apply.log" 2>&1 &
echo "apply pid=$!"

The wrapper is a file rather than an inline sh -c because RESOLVE_ARGS is a shell array and does not survive being flattened into a quoted string. It reads HA_ENTRY, WORK_SOURCE, HARNESS_MIGRATION_WORK and HARNESS_DAEMON_USER_ROOT from the environment, so they must be exported — which they are, if you followed the export blocks above. Note also node "$HA_ENTRY" rather than ha: the shell function from step 1 does not exist inside nohup.

Poll for the exit file, not for the pid — the file is what survives:

if [ -f "$HARNESS_MIGRATION_WORK/apply-exit.txt" ]; then
  cat "$HARNESS_MIGRATION_WORK/apply-exit.txt"; tail -20 "$HARNESS_MIGRATION_WORK/apply.log"
else
  echo "still running"
fi

While it runs, du -sh "$TARGET_REPO/harness" and the commit count in $TARGET_REPO/harness both climb — that is the only live progress signal there is. A stalled apply shows neither growing for many minutes.

Once it has finished, confirm the source was never written to:

export SOURCE_SHA_AFTER="$(COPYFILE_DISABLE=1 tar -cf - --exclude='harness/.git' -C "$ARCHIVE_SOURCE" harness | shasum -a 256 | awk '{print $1}')"
test "$SOURCE_SHA_BEFORE" = "$SOURCE_SHA_AFTER" && echo "source ledger untouched"

The --exclude must match step 2's exactly. Digesting different sets on the two sides guarantees a mismatch and tells you nothing.

If apply exits nonzero, keep its output, move the target aside, and restart from a fresh ha init. Never re-run apply against a partially imported target.

Then pack the new ledger's git repository. The importer commits once per event and never packs, so a freshly imported ledger is all loose objects — the 21,000-event migration produced 218,213 loose objects, zero packs, and an 18 GB .git for about 850 MB of actual content.

git -C "$TARGET_REPO/harness" gc --aggressive --prune=now
du -sh "$TARGET_REPO/harness/.git" "$TARGET_REPO/harness"
git -C "$TARGET_REPO/harness" rev-list --count HEAD
git -C "$TARGET_REPO/harness" fsck --no-progress

That run took the same ledger from 18 GB to a 181 MB .git in a single pack, with the commit count unchanged and fsck clean. The effect holds at small scale with the same shape and a far smaller bill: a 963-event ledger went from 104 MB / 10,332 loose objects / 0 packs to 19 MB / 0 loose / 1 pack in about 7 seconds, again with the commit count unchanged and fsck clean. Expect seconds on a small ledger, not the long wait the 18 GB figure suggests.

Do this before step 9 either way — it is the difference between handing the user a 19 GB directory and a 862 MB one, and after landing the daemon holds the repository.

Now execute the merge column recorded in step 5. $HARNESS_MIGRATION_WORK/preview-repository still holds the previous destination, and $WORK_SOURCE still holds the old files, so both sides remain readable:

diff -u "$TARGET_REPO/harness/adr/README.md" "$WORK_SOURCE/harness/adr/README.md" | head -40

For each row, edit the destination file to carry the project-specific content forward. Keep the current file's structure and add to it — do not paste the old file over it, which would undo the resolution that was just applied. Show the user the resulting diff. This is the last write of the migration.

9. Land the ledger

$TARGET_REPO/harness is a standalone git repository — its own .git, its own history, its own remote. That is true in both placements below, and it is the thing that must not be lost: a ledger is never a subdirectory of the project's repository. One ledger, mirrored by the checkouts that use it.

Local — the default. The ledger lives inside the project directory as <project>/harness, a repository of its own, and the project ignores it. This is the shape ha init produces for a new project and the shape previous generations used. Choose it unless the user says otherwise.

Central. The ledger lives outside any project, in a directory of its own, and is registered by absolute path. Choose it when the user tells you the ledger is shared — several machines mirroring one authoritative copy.

First: the machine needs a current-generation CLI that outlives this work directory

Read this before touching the destination. Everything up to here ran from $HARNESS_MIGRATION_WORK, which is disposable. The landed ledger is not: it needs a daemon serving it from here on, and that daemon must be the current generation — the whole reason for this migration is that the machine's installed ha belongs to the previous one, and a previous-generation daemon cannot serve a current-format ledger.

Check what the machine actually has — do not assume it has nothing. A current-generation ha is often already installed, built from this repository rather than from a registry:

env -u HARNESS_DAEMON_USER_ROOT command ha --version; echo "exit=$?"

A current-generation CLI prints a version and exits 0. A previous-generation one rejects the flag outright and exits nonzero:

{"ok":false,"command":"parse","error":{"code":"unknown_option",
 "hint":"Unknown option '--version' for 'ha'. Did you mean '--json'?"}}

Route on whether the flag is accepted, never on the number it prints. The version string is 0.1.0 and carries no generation marker, so it is the same on a current-generation global install and on the source checkout you have been running all along — seeing 0.1.0 twice tells you nothing about which build is which. Acceptance of --version is the whole signal; the number is noise.

If the flag is accepted, use that installation and skip to the ha_serving block below. Running the migration checkout would also work, but handing the user a command they already have beats handing them a checkout to maintain.

If it rejects, the installed CLI cannot serve what you are about to land, and there is nothing to npm install: @harness-anything/cli is not published (npm view returns 404). Two workable answers, in order of preference:

# preferred — build the checkout and install it on PATH, so `ha` just works
cd "$HARNESS_MIGRATION_WORK/ha-src/packages/cli" && npm run build && npm install -g .
command ha --version

# fallback — keep a durable checkout and invoke it by path
export HA_HOME="$HOME/.harness-cli-src"          # anywhere durable; not $HARNESS_MIGRATION_WORK
cp -R "$HARNESS_MIGRATION_WORK/ha-src" "$HA_HOME"
export HA_ENTRY="$HA_HOME/packages/cli/src/index.ts"
node "$HA_ENTRY" --version

The package's bin points into dist/, which a fresh clone does not contain — that is why the global install needs an explicit npm run build first, and why the skill has been running the TypeScript entry point directly up to now. A build is all that is missing; it is not an unavailable artifact.

Whichever branch you took, name the result once and use it for the rest of step 9, so the serving CLI and the throwaway migration entry point never get confused for each other:

ha_serving() { command ha "$@"; }           # the machine's ha is current-generation
# ha_serving() { node "$HA_ENTRY" "$@"; }   # ...or the durable checkout instead
ha_serving --version

Hand the user that same invocation — the exact command that now drives this ledger — and say plainly whether it replaces their existing ha. Do not leave them to discover it the first time ha task list fails.

Note also that env -u HARNESS_DAEMON_USER_ROOT ha … below resolves ha from PATH, which skips any shell function or alias the user has defined around it. If theirs injects flags — --actor, a default --root — those are silently dropped. This is not hypothetical: a real machine defines ha as a function wrapping command ha --actor human:<person>, so commands run through env are attributed to a different actor than the same commands typed by hand. Run type ha before relying on either form, and write command ha when you mean the binary.

The procedure below is the same for both placements. Only LEDGER_HOME differs.

# local (default) — the project directory the user is migrating
export LEDGER_HOME="/absolute/path/to/the/project"
# central — a directory of its own, outside every project
# export LEDGER_HOME="/absolute/path/the/user/chooses"

cd "$LEDGER_HOME"
# If the machine's own daemon already serves a ledger here, release it FIRST -- see below.
mv harness "harness.pre-migration-$(date +%Y%m%d-%H%M%S)"    # superseded, not disposable
cp -R "$TARGET_REPO/harness" ./harness

If the destination is already a live Harness workspace, release it before the mv, not after. Everything up to here ran against the throwaway migration daemon; the ledger you are replacing belongs to the machine's own daemon, which is a different registry and is holding an open cell and a writer lock on the directory you are about to move. Release it first, with HARNESS_DAEMON_USER_ROOT unset so the commands reach that daemon rather than the migration one:

env -u HARNESS_DAEMON_USER_ROOT command ha daemon repo unregister --repo-id <existing-repo-id>

The daemon keeps running and keeps serving its other repositories; only this ledger is released, which you can confirm by the writer lock next to it disappearing. Then do the mv and cp above.

A destination with no Harness yet has nothing to release, and this step is skipped.

Move the old ledger aside; do not delete it. The step 2 archive holds its content, but the directory is also a git repository with its own history, and this is the one moment in the migration where a mistake is discovered late. The same reasoning already governs the old runtime directory below: report it, hand over the path, and let the user delete it when they are satisfied. A rename is reversible in one command; rm -rf against a directory the skill does not own is not.

In a project, isolate the ledger from the project's own repository before committing anything. ha init does this on a fresh project, but registering an existing ledger does not, so do it here:

for rule in '/harness/' '/.harness/' '/harness.pre-migration-*/'; do
  grep -qxF "$rule" .gitignore 2>/dev/null || printf '%s\n' "$rule" >> .gitignore
done
git rm -r -q --cached --ignore-unmatch -- harness .harness

The third rule is load-bearing, and so is checking the rules one at a time. The mv above leaves a harness.pre-migration-<timestamp>/ directory sitting in the project root, and /harness/ does not match it — it matches only a directory named exactly harness. Without its own rule that directory

…(truncated)