diag-harness

Codex skill: kernel-version skew check for a scaffolded harness — the ADR-027 diagnostic UX loop.

What it does

Single-question check: does my local @metaharness/kernel match what this harness was scaffolded against? That's the cross-machine compatibility question almost every "this harness doesn't work" support ticket turns out to be.

Reads .harness/manifest.json:

Field	Source	Meaning
meta.surface	iter 56	Which surface produced the harness (cli or web-ui)
meta.kernel_version	iter 58	The @metaharness/kernel version stamped at scaffold time

Resolves the local @metaharness/kernel via createRequire rooted at the harness's own package.json (real Node resolution). Computes the skew verdict and prints a copy-pasteable next step.

Verdict	Exit	Message
match	0	PASS kernel versions match exactly
patch-diff	0	WARN patch-level skew (usually safe; may include bugfixes)
minor-diff	1	WARN minor-level skew (new kernel features may be missing) + Run: npm install @metaharness/kernel@X.Y.Z
major-diff	1	FAIL MAJOR skew — APIs may have changed; expect breakage + Run: npm install @metaharness/kernel@X.Y.Z
no .harness/manifest.json at path	2	FAIL no .harness/manifest.json found at this path

Usage from Codex

/diag-harness                           # cwd
/diag-harness path=./my-harness

Equivalent CLI

harness diag                            # cwd
harness diag ./my-harness               # explicit path
harness diag ./my-harness --json        # machine-readable for CI
harness diag ./my-harness --bundle      # support-ticket JSON (iter 90)

The --bundle form (iter 90) emits a single JSON snapshot of the diag report + sanitised manifest + @metaharness/* deps + Node/platform info — everything a maintainer needs to triage a bug report. Object keys matching secret|token|key|password|api_key are redacted so the bundle is safe to paste into a public GitHub issue.

Sample output

harness diag — checking /tmp/my-harness

  surface:              cli
  manifest kernel:      0.1.0
  installed kernel:     0.1.0

  PASS kernel versions match exactly

When to run

• After cloning someone else's harness — first thing
• After bumping @metaharness/kernel in a harness's package.json
• When harness doctor fails with cryptic shape errors (skew is the usual cause)
• In CI before any other harness subcommand — fail fast

Lifecycle position

scaffold (create-agent-harness)
    ↓
 your code lives in the harness
    ↓
 diag (this skill)           <- before anything else, check compatibility
    ↓
 doctor / validate / sign / publish

Related

• ADR-027 — CLI ↔ Web-UI integration (the parity contract diag enforces)
• iter 56 — manifest.meta.surface added
• iter 58 — manifest.meta.kernel_version stamped at scaffold time
• iter 66 — harness diag subcommand