patch.moi/docs/pages/tutorials/run-harness-maintenance-flow.md

title	description
Run the harness maintenance flow	Use the patch.moi harness repos to rehearse an upstream release and maintained fork update.

Run the harness maintenance flow

This tutorial runs the smallest real patch.moi maintenance loop. The upstream repo is harness/upstream. The maintained fork is harness/fork. The flow package is flows/patch-moi-harness.

There are two local operator paths:

• run the flow directly with bun run harness:flow
• run the same flow through the repo-native command workspace task

Both paths exercise the harness. The Patch service path still starts with feed intake, writes DATA_DIR records, creates a maintenance attempt, and dispatches the same kind of event through the workspace backend adapter.

1. Check out the harness repos

git submodule update --init --recursive
git -C harness/fork remote -v
git -C harness/fork status --short --branch

The fork should have origin, upstream, and jojo remotes. The flow can add the configured upstream remote when it is missing, but it will not invent the fork or service remotes.

2. Run the fixture event directly

CODEX_FLOW_FETCH=0 \
CODEX_FLOW_PUSH=0 \
bun run harness:flow

The fixture event is v0.1.3, which the current fork already contains. The flow should skip rebase work, run npm test and npm run pack:dry-run in the fork, report candidateRefs for the maintained fork branch, and leave the fork checkout unchanged.

3. Run the fixture through workspace autonomy

The repo also exposes the same fixture as a manual codex-flows workspace task:

CODEX_FLOW_FETCH=0 \
CODEX_FLOW_PUSH=0 \
bun run workspace:run:harness

That task is defined in .codex/workspace.toml as a command task that runs bun run harness:flow. It is intentionally unscheduled, so bun run workspace:tick is safe by default and explicit workspace run remains the operator action.

Use bun run workspace:doctor to inspect the repo-native workspace config and generated local run state. The generated local state is ignored by Git.

4. Try the workspace flow smoke task

The experimental workspace flow task dispatches a generated upstream.release event through a running Codex workspace backend:

cd ../codex-flows
bun run workspace:backend --cwd /home/peezy/meta-workspace/patch.moi

Then, from the patch.moi repo:

CODEX_WORKSPACE_BACKEND_WS_URL=ws://127.0.0.1:3586 \
CODEX_FLOW_FETCH=0 \
CODEX_FLOW_PUSH=0 \
bun run workspace:run:harness-flow

Use this only to exercise workspace-owned automation. It is not the product path for patch.moi feed intake, and it does not write patch.moi DATA_DIR maintenance-attempt records unless patch.moi itself dispatches the event.

5. Rehearse a real upstream release

Create a new upstream release in harness/upstream, then point the fixture or a feed event at the new tag:

cd harness/upstream
npm version patch --no-git-tag-version
npm test
git add package.json package-lock.json
git commit -m "Release harness package"
version=$(node -p "require('./package.json').version")
git tag "v${version}"
git push origin main "v${version}"

Run the harness flow again without disabling fetch:

bun run harness:flow <event-file>

Use an event file whose id, occurredAt, receivedAt, and payload.tag identify the new upstream tag. The flow rebases harness/fork onto that tag, verifies the fork package, reports the local candidate branch, and keeps pushes off.

6. Push only after review

When the local result is the maintained fork state you want:

CODEX_FLOW_PUSH=1 bun run harness:flow <event-file>

That pushes the rebased fork branch to the configured origin and jojo remotes with --force-with-lease and reports those pushed branch refs as candidate refs. Public npm publishing remains a separate trusted-publishing release path.