coding-agent-harness 1.0.7 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 1.1.0
+
+- Document the Node.js 24+ runtime baseline as a release-significant change and
+  move the next publish line to `1.1.0` instead of another patch release.
+- Add a `prepublishOnly` release gate that uses the source-safe dist bootstrap
+  to rebuild `dist/` and run the dist observation checker before `npm publish`.
+- Make the source-safe `postinstall.mjs` bootstrap fail with the package-level
+  missing-dist message when installed package contents are incomplete, instead
+  of attempting a source checkout build script that is not shipped.
+
+## 1.0.8
+
+- Preserve the executable bit for the packaged `dist/harness.mjs` npm bin
+  entry during dist builds and prepack.
+- Extend release observation checks to fail if the packed or installed
+  `harness` bin is not executable.
+- Add `migrate-structure --plan` to the dist and installed-package command
+  smoke matrix.
+
+## 1.0.7
+
+- Generate `harness init --add-npm-scripts` commands with
+  `npx --yes coding-agent-harness ...` so target projects can run Harness
+  scripts without adding a project dependency or relying on a global install.
+- Isolate the dist observation command matrix from local ignored docs by using
+  the minimal target-project fixture for target-facing commands.
+- Preserve the executable bit on the committed `dist/harness.mjs` CLI entry.
+
+## 1.0.6
+
+- Bump the npm package version after the 1.0.5 publication so the TypeScript
+  runtime-source migration can be published again.
+
 ## 1.0.5
 
 - Relicense the public package from MIT to AGPL-3.0-or-later.

package/CONTRIBUTING.md

@@ -4,8 +4,8 @@ Thanks for helping improve Coding Agent Harness. This repository contains the pu
 
 ## Before You Start
 
-- Use Node.js 18 or newer. CI currently runs on Node.js 20.
-- Install root dependencies with `npm install` from the repository root.
+- Use Node.js 24 or newer. CI should run on the minimum supported line.
+- Install root dependencies with `npm install` from the repository root. The install lifecycle generates the local `dist/` runtime; `dist/` is not tracked in Git.
 - If you change `harness-gui`, also run `npm ci` inside `harness-gui/`.
 - Keep pull requests focused. Separate documentation, CLI/runtime, template, preset, and GUI work when the changes are independent.
 
@@ -14,6 +14,7 @@ Thanks for helping improve Coding Agent Harness. This repository contains the pu
 | Path | Purpose |
 | --- | --- |
 | `scripts/` | Public CLI and implementation modules. |
+| `dist/` | Generated runtime output. It is published to npm but ignored in Git. |
 | `tests/` | Root package tests and dashboard smoke tests. |
 | `templates/`, `templates-zh-CN/` | Harness templates installed into target projects. |
 | `presets/` | Bundled Harness preset packages. |
@@ -39,8 +40,8 @@ docs row. For larger PRs or when you are unsure, run the full root suite.
 | Change type | Minimum local checks |
 | --- | --- |
 | Docs only | `git diff --check` |
-| CLI/runtime | `npm test`, `npm run check`, `git diff --check` |
-| Templates or examples | `npm test`, `node dist/harness.mjs check --profile target-project examples/minimal-project`, `git diff --check` |
+| CLI/runtime | `npm run typecheck`, `npm run typecheck:guards`, `npm test`, `npm run check`, `git diff --check` |
+| Templates or examples | `npm test`, `npm run build:runtime`, `node dist/harness.mjs check --profile target-project examples/minimal-project`, `git diff --check` |
 | Dashboard | `npm test`, `npm run smoke:dashboard`, `git diff --check` |
 | Package surface | `npm test`, `npm run pack:dry-run`, `git diff --check` |
 | GUI submodule | `cd harness-gui && npm ci && npm run typecheck && npm test && npm run build` |
@@ -49,6 +50,9 @@ Full root suite:
 
 ```bash
 npm install
+npm run build:runtime
+npm run typecheck
+npm run typecheck:guards
 npm test
 npm run smoke:dashboard
 npm run check
@@ -93,6 +97,6 @@ Use draft PRs for work that still needs design review, incomplete checks, or fol
 
 ## CI Expectations
 
-GitHub Actions validates the root package, source/package boundary, minimal target project, dashboard smoke path, npm package dry run, and GUI submodule typecheck/test/build path. A local run should match the CI commands closely enough that failures are reproducible.
+GitHub Actions validates the root TypeScript integrity gate (`npm run typecheck` and `npm run typecheck:guards`), root package tests, source/package boundary, minimal target project, dashboard smoke path, npm package dry run, and GUI submodule typecheck/test/build path. A local run should match the CI commands closely enough that failures are reproducible.
 
 Repository owners may configure branch protection and required checks separately in GitHub. Contributors do not need to manage those settings.

package/README.md

@@ -14,6 +14,8 @@ English | [简体中文](README.zh-CN.md) | [日本語](docs-release/intl/ja-JP.
 
 Coding Agent Harness is not another collection of chat prompts. It turns the durable facts that coding agents need into repository files: entry agreements, task plans, execution evidence, regression results, dashboards, and closeout records.
 
+Requires Node.js 24 or newer.
+
 The smallest loop is:
 
 - A human states the goal, and the agent reads the repository Harness first.
@@ -96,6 +98,14 @@ runtime. Target projects should not treat `planning/**/_task-template` or
 migration removes those generated legacy template directories when it finds
 them.
 
+Modules are registered in the root `harness.yaml` under `modules.items`.
+`harness module register` creates only the module-owned `brief.md` and
+`module_plan.md`, then regenerates `planning/modules/Module-Registry.md` as a
+read-only view. Task execution files such as `execution_strategy.md`,
+`visual_map.md`, `review.md`, and `walkthrough.md` are created under concrete
+project or module task directories, including
+`planning/modules/<key>/tasks/<task-id>/`.
+
 ### Safe Migration For Existing Projects
 
 Legacy project migration starts with a scan, a migration plan, a recommended migration mode, and user confirmation. Only then should the agent write files. Final status is proven with a dashboard and checks.
@@ -340,7 +350,7 @@ When the migration is complete, report the dynamic workbench URL or static dashb
 
 ## Contributing
 
-External contributors should start with [`CONTRIBUTING.md`](CONTRIBUTING.md). It covers repository layout, pull request expectations, root package checks, Dashboard smoke tests, npm package dry runs, and GUI submodule validation. The detailed public workflow also lives in [`docs-release/guides/contributing.md`](docs-release/guides/contributing.md).
+External contributors should start with [`CONTRIBUTING.md`](CONTRIBUTING.md). It covers repository layout, pull request expectations, enforced TypeScript integrity checks, root package checks, Dashboard smoke tests, npm package dry runs, and GUI submodule validation. The detailed public workflow also lives in [`docs-release/guides/contributing.md`](docs-release/guides/contributing.md).
 
 If you want your coding agent to make a contribution, send it this prompt:
 
@@ -351,7 +361,7 @@ Start from the latest main branch and create a new feature branch. Read README.m
 
 Keep the change scoped. Use only public repository files and do not rely on maintainer-local state, hidden workflows, credentials, generated dashboards, temporary files, or ignored local-only files.
 
-Run the checks that match the change. For docs-only changes, run git diff --check. For root package changes, run npm install, npm test, npm run smoke:dashboard, npm run check, node dist/harness.mjs check --profile target-project examples/minimal-project, npm run pack:dry-run, and git diff --check as relevant. If the change touches harness-gui, also run cd harness-gui && npm ci && npm run typecheck && npm test && npm run build.
+Run the checks that match the change. For docs-only changes, run git diff --check. For root package changes, run npm install, npm run build:runtime, npm run typecheck, npm run typecheck:guards, npm test, npm run smoke:dashboard, npm run check, node dist/harness.mjs check --profile target-project examples/minimal-project, npm run pack:dry-run, and git diff --check as relevant. If the change touches harness-gui, also run cd harness-gui && npm ci && npm run typecheck && npm test && npm run build. The source repository ignores `dist/`; npm install, prepare, prepack, and the root npm scripts regenerate it when needed.
 
 When done, summarize what changed, list verification results, call out any skipped checks with reasons, and prepare the PR using the repository template.
 ```

package/README.zh-CN.md

@@ -14,6 +14,8 @@
 
 Coding Agent Harness 不是另一个聊天提示词集合。它把 Agent 长程开发需要依赖的事实沉淀到仓库：入口协议、任务计划、执行证据、回归结果、Dashboard 和收口记录。
 
+需要 Node.js 24 或更新版本。
+
 最小闭环是：
 
 - 人提出目标，Agent 先读仓库里的 Harness 协议。
@@ -86,6 +88,12 @@ Harness 自带内置 Preset，`harness init` 会把它们 seed 到目标项目
 默认任务模板和模块模板来自当前安装的 npm 包，在命令运行时读取。目标项目不应该把
 `planning/**/_task-template` 或 `planning/**/_module-template` 当作活跃状态；v2 结构迁移发现这些旧生成模板目录时会直接清理。
 
+模块统一注册在根 `harness.yaml` 的 `modules.items` 里。`harness module register`
+只创建模块根目录拥有的 `brief.md` 和 `module_plan.md`，然后把
+`planning/modules/Module-Registry.md` 重新生成为只读视图。`execution_strategy.md`、
+`visual_map.md`、`review.md`、`walkthrough.md` 等执行合同属于具体任务目录，例如
+`planning/modules/<key>/tasks/<task-id>/`。
+
 ### 旧项目也能迁移
 
 旧项目迁移不是直接套模板。标准流程是：先扫描项目，生成迁移计划，推荐迁移模式，向用户提问确认，再执行迁移，最后用 Dashboard 和检查结果证明迁移状态。
@@ -320,7 +328,7 @@ npx --yes coding-agent-harness new-task --budget complex --preset legacy-migrati
 
 ## 参与贡献
 
-外部贡献者请先阅读 [`CONTRIBUTING.md`](CONTRIBUTING.md)。它说明仓库结构、PR 要求、根包检查、Dashboard smoke test、npm package dry run 和 GUI 子模块验证。中文详细流程见 [`docs-release/guides/contributing.zh-CN.md`](docs-release/guides/contributing.zh-CN.md)。
+外部贡献者请先阅读 [`CONTRIBUTING.md`](CONTRIBUTING.md)。它说明仓库结构、PR 要求、enforced TypeScript integrity 检查、根包检查、Dashboard smoke test、npm package dry run 和 GUI 子模块验证。中文详细流程见 [`docs-release/guides/contributing.zh-CN.md`](docs-release/guides/contributing.zh-CN.md)。
 
 如果你想让自己的 Coding Agent 帮你改这个仓库，可以把下面这段发给它：
 
@@ -331,7 +339,7 @@ npx --yes coding-agent-harness new-task --budget complex --preset legacy-migrati
 
 改动要保持聚焦。只使用公开仓库文件；不要依赖维护者本地状态、隐藏工作流、凭据、生成的 Dashboard、临时文件或被 ignore 的本地专用文件。
 
-根据改动范围运行检查。仅文档改动至少运行 git diff --check。根包相关改动按需运行 npm install、npm test、npm run smoke:dashboard、npm run check、node dist/harness.mjs check --profile target-project examples/minimal-project、npm run pack:dry-run 和 git diff --check。如果改到 harness-gui，还要运行 cd harness-gui && npm ci && npm run typecheck && npm test && npm run build。
+根据改动范围运行检查。仅文档改动至少运行 git diff --check。根包相关改动按需运行 npm install、npm run build:runtime、npm run typecheck、npm run typecheck:guards、npm test、npm run smoke:dashboard、npm run check、node dist/harness.mjs check --profile target-project examples/minimal-project、npm run pack:dry-run 和 git diff --check。如果改到 harness-gui，还要运行 cd harness-gui && npm ci && npm run typecheck && npm test && npm run build。源码仓不跟踪 `dist/`；npm install、prepare、prepack 和根仓 npm scripts 会按需重新生成。
 
 完成后，请总结改了什么，列出验证结果，说明任何未运行检查及原因，并按仓库 PR 模板准备 PR。
 ```

package/SKILL.md

@@ -31,6 +31,16 @@ description: >
 - **严肃项目用顶级模型。** 便宜模型的返工成本远高于差价。
 - **强制流程优于口头约定。** 每个步骤都应该是 agent 可自主执行的。
 
+## Product Contract
+
+Full Harness 与后续 Lite Skill 的共享任务语义由 Document Contract Kernel
+约束，公开源位于 `docs-release/architecture/document-contract-kernel/README.md`。
+凡是改变 AGENTS、context、task package、progress、walkthrough、review、
+regression 或 lessons 基础语义的改动，必须按该 contract 同步 Full/Lite
+overlay 与 compatibility matrix；Full-only 的 CLI、Dashboard、Preset、
+generated ledger、Module Registry、lifecycle command、runtime requirement
+不得泄漏进 Lite source。
+
 ---
 
 ## 主执行 SOP
@@ -64,7 +74,8 @@ CLI 示例默认使用目标项目可调用的 `harness` 命令。执行前先
 `command -v harness`；如果没有，不要静默全局安装，按安装指南询问用户是否
 允许 `npm install -g coding-agent-harness`。未获明确同意时，用
 `npx --yes coding-agent-harness <command>` 执行同一条命令。只有维护本源码
-checkout 时，才把 `harness` 替换为 `node dist/harness.mjs`。
+checkout 时，才把 `harness` 替换为 `node dist/harness.mjs`；源码仓的
+`dist/` 是生成物，若不存在先运行 `npm install` 或 `npm run build:runtime`。
 
 ### Agent 安装合同
 
@@ -252,7 +263,7 @@ harness bootstrap 完成后，项目中至少应存在以下文件：
 - [ ] `coding-agent-harness/governance/standards/walkthrough-template.md`
 - [ ] `coding-agent-harness/governance/generated/Closeout-Index.md`
 - [ ] `coding-agent-harness/governance/lessons/`（空目录 + .gitkeep）
-- [ ] `coding-agent-harness/governance/_archive/`（空目录 + .gitkeep）
+- [ ] `coding-agent-harness/governance/archive/`（空目录 + .gitkeep）
 - [ ] `coding-agent-harness/governance/generated/Harness-Ledger.md`
 - [ ] `coding-agent-harness/governance/standards/external-source-intake-standard.md`
 - [ ] `coding-agent-harness/governance/standards/harness-ledger-standard.md`
@@ -339,7 +350,7 @@ harness 搭建完成后，每个 feature 从想法到代码的标准流程：
 | Long-Running Task Contract | `templates/planning/long-running-task-contract.md` | 长程任务授权、review loop 和停止条件 |
 | Module Session Prompt | `templates/planning/module_session_prompt.md` | 模块并行开发会话冷启动 |
 | Walkthrough | `templates/walkthrough/walkthrough-template.md` | 任务收口记录 |
-| Closeout Index | `templates/walkthrough/walkthrough-template.md` | closed task 索引和收口证据 |
+| Closeout Index | `governance rebuild` generated output | `governance/generated/Closeout-Index.md` 由 task closeout metadata 重建，无独立模板 |
 | Testing Standard | `templates/reference/testing-standard.md` | 测试、冒烟和回归规范 |
 | Execution Workflow | `templates/reference/execution-workflow-standard.md` | 执行、提交、PR 和证据记录 |
 | Delivery Operating Model Standard | `templates/reference/delivery-operating-model-standard.md` | 交付组织模型选择 |

package/dist/build-dist.mjs

@@ -1,10 +1,9 @@
 #!/usr/bin/env node
-// @ts-nocheck
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const typescriptVersion = "5.9.3";
 export function buildRuntimeDist({ projectRoot = repoRoot, configPath = path.join(projectRoot, "tsconfig.dist.json"), outDir = path.join(projectRoot, "dist"), } = {}) {
@@ -28,14 +27,18 @@ export function buildRuntimeDist({ projectRoot = repoRoot, configPath = path.joi
         };
     }
     fs.rmSync(buildOutDir, { recursive: true, force: true });
-    const emit = spawnSync("npm", ["exec", "--yes", "--package", `typescript@${typescriptVersion}`, "--", "tsc", "-p", absoluteConfig, "--outDir", buildOutDir, "--noCheck"], {
+    const npmArgs = ["exec", "--yes", "--package", `typescript@${typescriptVersion}`, "--", "tsc", "-p", absoluteConfig, "--outDir", buildOutDir, "--noCheck"];
+    const npmExecPath = process.env.npm_execpath;
+    const command = npmExecPath ? process.execPath : process.platform === "win32" ? "npm.cmd" : "npm";
+    const commandArgs = npmExecPath ? [npmExecPath, ...npmArgs] : npmArgs;
+    const emit = spawnSync(command, commandArgs, {
         cwd: absoluteProjectRoot,
         encoding: "utf8",
     });
     if (emit.status !== 0) {
         return {
             ok: false,
-            error: `TypeScript dist build failed\nSTDOUT:\n${emit.stdout}\nSTDERR:\n${emit.stderr}`,
+            error: `TypeScript dist build failed${emit.error ? `\nERROR:\n${emit.error.message}` : ""}\nSTDOUT:\n${emit.stdout ?? ""}\nSTDERR:\n${emit.stderr ?? ""}`,
             status: emit.status,
         };
     }
@@ -43,6 +46,10 @@ export function buildRuntimeDist({ projectRoot = repoRoot, configPath = path.joi
         syncDirectory(buildOutDir, absoluteOutDir);
         fs.rmSync(buildOutDir, { recursive: true, force: true });
     }
+    restoreExecutableEntrypoints({
+        outDir: absoluteOutDir,
+        binRelativePaths: ["harness.mjs"],
+    });
     const files = collectFiles(absoluteOutDir).filter((file) => file.endsWith(".mjs")).sort();
     const relativeFiles = files.map((file) => toPosix(path.relative(absoluteOutDir, file)));
     const requiredFiles = [
@@ -126,6 +133,15 @@ function syncDirectory(sourceDir, targetDir) {
         fs.rmSync(path.join(targetDir, entry), { recursive: true, force: true });
     }
 }
+function restoreExecutableEntrypoints({ outDir, binRelativePaths }) {
+    for (const relativePath of binRelativePaths) {
+        const file = path.join(outDir, relativePath);
+        if (!fs.existsSync(file))
+            continue;
+        const stat = fs.statSync(file);
+        fs.chmodSync(file, stat.mode | 0o755);
+    }
+}
 function toPosix(value) {
     return value.split(path.sep).join("/");
 }
@@ -165,13 +181,23 @@ function requireValue(argv, index, option) {
         throw new Error(`${option} requires a value`);
     return value;
 }
-if (import.meta.url === `file://${process.argv[1]}`) {
+function isMainModule() {
+    if (!process.argv[1])
+        return false;
+    try {
+        return fs.realpathSync.native(fileURLToPath(import.meta.url)) === fs.realpathSync.native(process.argv[1]);
+    }
+    catch {
+        return import.meta.url === pathToFileURL(process.argv[1]).href;
+    }
+}
+if (isMainModule()) {
     let options;
     try {
         options = parseArgs(process.argv.slice(2));
     }
     catch (error) {
-        console.error(error.message);
+        console.error(error instanceof Error ? error.message : String(error));
         process.exit(1);
     }
     const result = buildRuntimeDist(options);

package/dist/check-dist-observation.mjs

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-// @ts-nocheck
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -21,16 +20,18 @@ export function checkDistObservation({ projectRoot = defaultProjectRoot, runPack
         return { ok: false, failures, observations };
     expectEqual(failures, "package-bin-not-dist", pkg.bin?.harness, "dist/harness.mjs", "package bin.harness must resolve to dist/harness.mjs");
     const distRuntimeScripts = {
-        check: "node dist/harness.mjs check --profile source-package .",
-        "check:private": "node dist/harness.mjs check --profile private-harness .harness-private",
-        status: "node dist/harness.mjs status --json .",
-        dashboard: "node dist/harness.mjs dashboard --out tmp/harness-dashboard.html examples/minimal-project",
-        "dashboard:folder": "node dist/harness.mjs dashboard --out-dir tmp/harness-dashboard examples/minimal-project",
-        postinstall: "node dist/postinstall.mjs",
-        "observe:dist": "node dist/check-dist-observation.mjs --skip-pack --skip-install-smoke",
+        check: ["run-dist.mjs", "harness.mjs", "check", "--profile", "source-package"],
+        "check:private": ["run-dist.mjs", "harness.mjs", "check", "--profile", "private-harness"],
+        status: ["run-dist.mjs", "harness.mjs", "status", "--json"],
+        dashboard: ["run-dist.mjs", "harness.mjs", "dashboard", "--out"],
+        "dashboard:folder": ["run-dist.mjs", "harness.mjs", "dashboard", "--out-dir"],
+        postinstall: ["postinstall.mjs"],
+        prepare: ["postinstall.mjs", "--build-only"],
+        prepublishOnly: ["run-dist.mjs", "check-dist-observation.mjs", "--skip-install-smoke"],
+        "observe:dist": ["run-dist.mjs", "check-dist-observation.mjs", "--skip-pack", "--skip-install-smoke"],
     };
-    for (const [name, expected] of Object.entries(distRuntimeScripts)) {
-        expectEqual(failures, `package-script-${name}-not-dist`, pkg.scripts?.[name], expected, `package script ${name} must run from dist`);
+    for (const [name, tokens] of Object.entries(distRuntimeScripts)) {
+        expectScriptIncludes(failures, `package-script-${name}-not-source-safe-dist`, pkg.scripts?.[name], tokens, `package script ${name} must run through the source-safe dist bootstrap`);
     }
     observations.packageRuntime = {
         bin: pkg.bin?.harness,
@@ -48,20 +49,30 @@ export function checkDistObservation({ projectRoot = defaultProjectRoot, runPack
             failures.push({ code: "pack-dry-run-failed", message: `npm pack dry-run failed\nSTDOUT:\n${pack.stdout}\nSTDERR:\n${pack.stderr}` });
         }
         else {
-            const packed = JSON.parse(pack.stdout)[0].files.map((file) => file.path).sort();
+            const packedEntries = JSON.parse(pack.stdout)[0]?.files ?? [];
+            const packed = packedEntries.map((file) => file.path).sort();
+            const packedModeByPath = new Map(packedEntries.map((file) => [file.path, file.mode]));
+            const distHarnessMode = packedModeByPath.get("dist/harness.mjs");
             observations.package = {
                 entryCount: packed.length,
                 hasDistHarness: packed.includes("dist/harness.mjs"),
                 hasDistPostinstall: packed.includes("dist/postinstall.mjs"),
                 hasDistObservationGate: packed.includes("dist/check-dist-observation.mjs"),
+                hasPostinstallBootstrap: packed.includes("postinstall.mjs"),
+                hasRunDistBootstrap: packed.includes("run-dist.mjs"),
                 hasScriptsHarness: packed.includes("scripts/harness.mjs"),
                 hasScripts: packed.some((file) => file.startsWith("scripts/")),
                 hasTests: packed.some((file) => file.startsWith("tests/")),
+                distHarnessMode,
+                distHarnessExecutable: typeof distHarnessMode === "number" && Boolean(distHarnessMode & 0o111),
             };
-            for (const required of ["dist/harness.mjs", "dist/postinstall.mjs", "dist/check-dist-observation.mjs"]) {
+            for (const required of ["postinstall.mjs", "run-dist.mjs", "dist/harness.mjs", "dist/postinstall.mjs", "dist/check-dist-observation.mjs"]) {
                 if (!packed.includes(required))
                     failures.push({ code: "packed-file-missing", file: required, message: `package missing ${required}` });
             }
+            if (!observations.package.distHarnessExecutable) {
+                failures.push({ code: "packed-bin-not-executable", file: "dist/harness.mjs", mode: distHarnessMode, message: "package bin dist/harness.mjs must be executable" });
+            }
             if (observations.package.hasScripts)
                 failures.push({ code: "package-includes-scripts", message: "package must not include scripts/** after historical shim deletion" });
             if (observations.package.hasTests)
@@ -133,6 +144,7 @@ function runMatrix(root, failures, commandMatrix) {
         { id: "source-check", args: ["check", "--profile", "source-package", "."] },
         { id: "target-check", args: ["check", "--profile", "target-project", "examples/minimal-project"] },
         { id: "migrate-plan", args: ["migrate-plan", "--json", "--limit", "20", "examples/minimal-project"] },
+        { id: "migrate-structure-plan", args: ["migrate-structure", "--plan", "--json", "examples/minimal-project"] },
         { id: "dashboard", args: ["dashboard", "--out-dir", path.join("tmp", `pr-27-observation-dashboard-${process.pid}`), "examples/minimal-project"] },
     ];
     for (const entry of matrix) {
@@ -193,7 +205,12 @@ function runInstalledPackageSmoke(root, failures, observations) {
         failures.push({ code: "install-smoke-pack-failed", message: `npm pack failed\nSTDOUT:\n${pack.stdout}\nSTDERR:\n${pack.stderr}` });
         return;
     }
-    const tarball = path.join(packDir, pack.stdout.trim().split(/\r?\n/).at(-1));
+    const tarballName = pack.stdout.trim().split(/\r?\n/).at(-1);
+    if (!tarballName) {
+        failures.push({ code: "install-smoke-pack-empty", message: "npm pack did not print a tarball name" });
+        return;
+    }
+    const tarball = path.join(packDir, tarballName);
     fs.writeFileSync(path.join(consumer, "package.json"), JSON.stringify({ private: true, type: "module" }, null, 2));
     const install = spawnSync("npm", ["install", "--silent", "--no-audit", "--no-fund", tarball], {
         cwd: consumer,
@@ -211,11 +228,15 @@ function runInstalledPackageSmoke(root, failures, observations) {
     if (!pkg)
         return;
     const binTarget = fs.existsSync(bin) ? fs.readlinkSync(bin) : "";
-    observations.installSmoke = {
+    const installedBinFile = path.join(packageRoot, "dist/harness.mjs");
+    const installedBinMode = fs.existsSync(installedBinFile) ? fs.statSync(installedBinFile).mode : undefined;
+    const installSmoke = {
         nodeVersion,
         tempRoot,
         binTarget,
         bin: pkg.bin?.harness,
+        binMode: installedBinMode,
+        binExecutable: typeof installedBinMode === "number" && Boolean(installedBinMode & 0o111),
         postinstall: pkg.scripts?.postinstall,
         observeDist: pkg.scripts?.["observe:dist"],
         hasTests: fs.existsSync(path.join(packageRoot, "tests")),
@@ -223,48 +244,60 @@ function runInstalledPackageSmoke(root, failures, observations) {
         scriptsDisabled: [],
         steps: [],
     };
+    observations.installSmoke = installSmoke;
     expectEqual(failures, "installed-bin-not-dist", pkg.bin?.harness, "dist/harness.mjs", "installed package bin.harness must resolve to dist/harness.mjs");
-    expectEqual(failures, "installed-postinstall-not-dist", pkg.scripts?.postinstall, "node dist/postinstall.mjs", "installed package postinstall must resolve to dist/postinstall.mjs");
-    expectEqual(failures, "installed-observe-dist-not-dist", pkg.scripts?.["observe:dist"], "node dist/check-dist-observation.mjs --skip-pack --skip-install-smoke", "installed observe:dist must resolve to dist/check-dist-observation.mjs");
+    expectScriptIncludes(failures, "installed-postinstall-not-source-safe", pkg.scripts?.postinstall, ["postinstall.mjs"], "installed package postinstall must use the source-safe bootstrap");
+    expectScriptIncludes(failures, "installed-observe-dist-not-source-safe", pkg.scripts?.["observe:dist"], ["run-dist.mjs", "check-dist-observation.mjs"], "installed observe:dist must use the source-safe dist bootstrap");
     if (!binTarget.includes("dist/harness.mjs")) {
         failures.push({ code: "installed-bin-link-not-dist", message: `installed bin link does not target dist/harness.mjs: ${binTarget}` });
     }
-    for (const relative of ["dist/harness.mjs", "dist/postinstall.mjs", "dist/check-dist-observation.mjs"]) {
+    if (!installSmoke.binExecutable) {
+        failures.push({ code: "installed-bin-not-executable", file: "dist/harness.mjs", mode: installedBinMode, message: "installed package bin dist/harness.mjs must be executable" });
+    }
+    for (const relative of ["postinstall.mjs", "run-dist.mjs", "dist/harness.mjs", "dist/postinstall.mjs", "dist/check-dist-observation.mjs"]) {
         if (!fs.existsSync(path.join(packageRoot, relative)))
             failures.push({ code: "installed-file-missing", file: relative, message: `installed package missing ${relative}` });
     }
-    if (observations.installSmoke.hasTests)
+    if (installSmoke.hasTests)
         failures.push({ code: "installed-package-includes-tests", message: "installed package must not include tests/**" });
-    if (observations.installSmoke.hasScripts)
+    if (installSmoke.hasScripts)
         failures.push({ code: "installed-package-includes-scripts", message: "installed package must not include scripts/** after historical shim deletion" });
     const installedScripts = path.join(packageRoot, "scripts");
     if (fs.existsSync(installedScripts)) {
         fs.renameSync(installedScripts, `${installedScripts}.disabled-by-dist-observation`);
-        observations.installSmoke.scriptsDisabled.push("scripts/");
+        installSmoke.scriptsDisabled.push("scripts/");
     }
     const runtimeEnv = isolatedEnv({ nodeBin, home, extraPath: [path.join(consumer, "node_modules", ".bin")] });
-    runInstalledMatrix(root, runtimeEnv, failures, observations.installSmoke.steps);
+    runInstalledMatrix(root, runtimeEnv, failures, installSmoke.steps);
     const postinstall = spawnSync(node24, [path.join(packageRoot, "dist/postinstall.mjs")], {
         cwd: packageRoot,
         encoding: "utf8",
         env: { ...runtimeEnv, CODING_AGENT_HARNESS_SKIP_POSTINSTALL: "1" },
     });
-    observations.installSmoke.steps.push({ id: "installed-dist-postinstall", status: postinstall.status });
+    installSmoke.steps.push({ id: "installed-dist-postinstall", status: postinstall.status });
     if (postinstall.status !== 0)
         failures.push({ code: "installed-postinstall-failed", message: `installed dist postinstall failed\nSTDOUT:\n${postinstall.stdout}\nSTDERR:\n${postinstall.stderr}` });
+    const postinstallBootstrap = spawnSync(node24, [path.join(packageRoot, "postinstall.mjs")], {
+        cwd: packageRoot,
+        encoding: "utf8",
+        env: { ...runtimeEnv, CODING_AGENT_HARNESS_SKIP_POSTINSTALL: "1" },
+    });
+    installSmoke.steps.push({ id: "installed-postinstall-bootstrap", status: postinstallBootstrap.status });
+    if (postinstallBootstrap.status !== 0)
+        failures.push({ code: "installed-postinstall-bootstrap-failed", message: `installed postinstall bootstrap failed\nSTDOUT:\n${postinstallBootstrap.stdout}\nSTDERR:\n${postinstallBootstrap.stderr}` });
     const installedObservation = spawnSync(node24, [path.join(packageRoot, "dist/check-dist-observation.mjs"), "--project-root", packageRoot, "--skip-pack", "--skip-install-smoke", "--skip-command-matrix", "--json"], {
         cwd: packageRoot,
         encoding: "utf8",
         env: runtimeEnv,
         maxBuffer: 32 * 1024 * 1024,
     });
-    observations.installSmoke.steps.push({ id: "installed-observation", status: installedObservation.status });
+    installSmoke.steps.push({ id: "installed-observation", status: installedObservation.status });
     if (installedObservation.status !== 0) {
         failures.push({ code: "installed-observation-failed", message: `installed observation failed\nSTDOUT:\n${installedObservation.stdout}\nSTDERR:\n${installedObservation.stderr}` });
     }
     else {
         const installedResult = JSON.parse(installedObservation.stdout);
-        observations.installSmoke.observationOk = installedResult.ok;
+        installSmoke.observationOk = installedResult.ok;
         if (!installedResult.ok)
             failures.push({ code: "installed-observation-not-ok", message: JSON.stringify(installedResult.failures, null, 2) });
     }
@@ -278,6 +311,7 @@ function runInstalledMatrix(root, runtimeEnv, failures, steps) {
         { id: "installed-source-check", cwd: root, args: ["check", "--profile", "source-package", "."] },
         { id: "installed-target-check", cwd: root, args: ["check", "--profile", "target-project", "examples/minimal-project"] },
         { id: "installed-migrate-plan", cwd: root, args: ["migrate-plan", "--json", "--limit", "20", "examples/minimal-project"] },
+        { id: "installed-migrate-structure-plan", cwd: root, args: ["migrate-structure", "--plan", "--json", "examples/minimal-project"] },
         { id: "installed-dashboard", cwd: root, args: ["dashboard", "--out-dir", path.join("tmp", `pr-27-installed-observation-dashboard-${process.pid}`), "examples/minimal-project"] },
     ];
     for (const entry of matrix) {
@@ -306,7 +340,7 @@ function findNode24() {
         path.join(os.homedir(), ".nvm", "versions", "node", "v24.13.1", "bin", "node"),
         "/opt/homebrew/opt/node@24/bin/node",
         "/usr/local/opt/node@24/bin/node",
-    ].filter(Boolean);
+    ].filter(isNonEmptyString);
     for (const candidate of candidates) {
         if (!fs.existsSync(candidate))
             continue;
@@ -316,7 +350,10 @@ function findNode24() {
     }
     return undefined;
 }
-function isolatedEnv({ nodeBin, home = process.env.HOME, extraPath = [] }) {
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+function isolatedEnv({ nodeBin, home = process.env.HOME || os.homedir(), extraPath = [], }) {
     return {
         ...process.env,
         HOME: home,
@@ -329,14 +366,22 @@ function readJson(file, failures, code) {
         return JSON.parse(fs.readFileSync(file, "utf8"));
     }
     catch (error) {
-        failures.push({ code, message: `failed to read ${file}: ${error.message}` });
+        failures.push({ code, message: `failed to read ${file}: ${errorMessage(error)}` });
         return undefined;
     }
 }
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
 function expectEqual(failures, code, actual, expected, message) {
     if (actual !== expected)
         failures.push({ code, actual, expected, message });
 }
+function expectScriptIncludes(failures, code, script, tokens, message) {
+    if (typeof script !== "string" || tokens.some((token) => !script.includes(token)) || script.includes("scripts/")) {
+        failures.push({ code, actual: script, expectedTokens: tokens, message });
+    }
+}
 function parseImportSpecifiers(content) {
     const specifiers = [];
     for (const match of content.matchAll(/\bfrom\s*["']([^"']+)["']/g))
@@ -413,7 +458,7 @@ if (isMainModule()) {
         options = parseArgs(process.argv.slice(2));
     }
     catch (error) {
-        console.error(error.message);
+        console.error(errorMessage(error));
         process.exit(1);
     }
     const result = checkDistObservation(options);

package/dist/check-harness.mjs

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-// @ts-nocheck
 import fs from "node:fs";
 import path from "node:path";
 import { checkModuleParallelStructure } from "./lib/check-module-parallel.mjs";