Make Harness as Code safe to install and execute

Traceability

• Spec ID: harness-as-code-v0.1
• Status: Implemented

Intent

Ship the first production-ready @qoder-ai/harness package as a parseable, lockable, and explainable assembly language for coding-agent harnesses. A resolved revision must distinguish the strength declared by a host binding from the strength the v0.1 executor can actually materialize, reject unsafe or ambiguous assemblies before execution, and install, build, test, and pack from the repository's normal dependency and CI workflow.

The v0.1 executors materialize components as prompt instructions. They may therefore realize at most advisory strength. Bindings may declare future wired or enforced host mechanisms, but those declarations are reported as degraded rather than presented as observed runtime guarantees.

Acceptance Scenarios

• AC-1: One or more .harness sources compile into schema-valid versioned IR, with stable diagnostics for parser, linker, semantic, and cross-file declaration conflicts.
• AC-2: Duplicate component ids, composition ids, exact plugin versions, or component/host bindings fail compilation even when the conflicting declarations are split across source files. Invalid exact semantic versions, duplicate plugin includes, and repeated component inputs/outputs also fail before resolution.
• AC-3: Resolution records both declared and materialized strength. The v0.1 runtime caps materialized strength at advisory, applies minimum, preferred, and on-degrade to that effective strength, and never describes an unmaterialized wired or enforced mechanism as realized.
• AC-4: An executor rejects a revision whose target host differs from the executor host before starting an SDK session or child process.
• AC-5: Qoder execution uses the official Agent SDK with explicit authentication, cwd, streaming output, and tool-authorization seams. Pi execution uses the current non-deprecated SDK and ModelRuntime API, honors the task working directory, disables native tools in the advisory-only v0.1 path, and reports a missing optional runtime dependency with actionable guidance. Pi model failures propagate through the run result and sessions are disposed after a run. Qoder streams that terminate without a result message fail closed.
• AC-6: Pi package materialization emits SKILL.md only for advisory skill-kind contracts, produces valid front matter for arbitrary DSL string descriptions, stamps revision provenance, and fails closed when the target directory already contains files.
• AC-7: The repository's root install and CI workflow installs this workspace, regenerates the Langium sources, type-checks/builds the package, runs its behavior tests on Windows, macOS, and Linux, and detects stale generated artifacts.
• AC-8: npm pack contains the documented public exports, declarations, example, README, and license without source-local dependencies, caches, or absolute paths; a clean temporary install can import and exercise the public API.
• AC-9: The package development guide describes supported Node and Pi SDK versions, the declared-versus-materialized strength boundary, focused commands, and current v0.1 limitations without claiming native host evidence.

Non-goals

• Installing or managing native Qoder hooks or Pi extensions in v0.1.
• Claiming wired or enforced runtime strength without a future native materialization and evidence-receipt contract.
• Adding another Coding Agent host adapter.
• Publishing the package to the npm registry in this change.
• Changing Better Harness release notes, versions, roadmaps, or changelog.
• Providing a full CLI, language server, editor extension, remote registry, or dependency solver beyond the in-bundle semver selection API.

Plan and Tasks

1. Tighten compiler semantic validation across the complete source set and keep diagnostics source/line-qualified.
2. Extend realization IR with declared strength and make the v0.1 resolver compute effective advisory materialization before applying degradation policy.
3. Add shared executor host validation, integrate the official Qoder and Pi SDKs, and make Pi skill materialization kind-safe and front-matter-safe.
4. Add the package as a root npm workspace, refresh the lockfile, expose root build/test/generated-source gates, and wire them into the OS matrix CI.
5. Expand behavior tests for every repaired failure mode, public exports, clean-pack import, and generated artifacts.
6. Validate a clean install, build, focused tests, root gates, package contents, temporary consumer import, and locally available host surfaces.

Test and Review Evidence

• AC-1/AC-2: package compiler tests use multi-source duplicate fixtures and assert structured diagnostics; they pass as part of the 38-test package run.
• AC-3: resolver tests cover satisfied, degraded-report, degraded-fail, and below-minimum paths against declared and materialized strengths.
• AC-4/AC-5: executor tests assert that mismatched hosts never invoke SDK loaders, that Qoder uses explicit auth/tool options, and that Pi uses ModelRuntime.create with the task cwd, selected model, and noTools: "all". Installed-package contract tests load both SDKs. A native Qoder SDK smoke returned exactly HARNESS_QODER_REVIEW_OK; native Pi inference was not run because this process had neither DEEPSEEK_API_KEY nor configured DeepSeek authentication.
• AC-6: temporary-directory tests inspect the returned file set and parse-safe generated front matter for skill and non-skill contracts.
• AC-7: npm ci --ignore-scripts --registry=https://registry.npmjs.org, an explicit Qoder SDK rebuild to restore its intentionally skipped worker postinstall, and npm run check passed. The final run covered 1,324 repository tests, 38 package tests, generated-source verification, TypeScript build, and pack verification. CI runs package gates on Windows, macOS, and Linux with Node 22.20.0 plus Linux with Node 24.
• AC-8: npm pack --workspace @qoder-ai/harness ran the package prepack gate and produced a 36-file, 27.2 kB tarball without the removed executor or source-local artifacts. A clean temporary install audited 160 dependencies with zero vulnerabilities and completed a Node ESM import/compile/resolve smoke through the public API.
• AC-9: README review against the package manifest and observed validation commands.
• Full regression: npm run check passed; root pack verification reported 523 npm entries and 545 runtime-zip entries. The focused documentation link graph passed all six assertions, and npm audit --audit-level=high reported zero vulnerabilities after upgrading Pi to 0.84.2.
• Risk: generated Langium output can drift from its grammar. CI regenerates and rejects a non-empty generated-source diff.
• Risk: adding a root workspace changes the lockfile and install graph. Review the final lockfile diff and keep package dependencies scoped to the workspace.
• Risk: native host and model availability vary by machine. Deterministic tests remain authoritative; native smoke is reported separately and never replaces package or fixture evidence.