@mstar-harness/engine 2.1.0 → 2.2.0

package/README.md

@@ -19,7 +19,7 @@ const version = readHarnessVersion(); // "1.8.8" — monorepo root package.json
 ## Scope
 
 - Importable library only — **no `bin`**; the CLI (`@mstar-harness/cli`) wraps engine functions as thin `mstar …` subcommands.
-- Dependencies: `node:*` only (zero external runtime deps — all validators hand-rolled; ajv pruned as phantom, zod removed 2026-08-08).
+- Dependencies: `node:*` only (zero external runtime deps — all validators hand-rolled; ajv and zod were pruned as phantom dependencies).
 - Skill prose stays authoritative; engine exports are the machine-checkable mirror of the rules the `mstar-*` skills state.
 
 ## License

package/dist/engine.js

@@ -83,24 +83,52 @@ function readHarnessVersion() {
 }
 // src/path.ts
 import { mkdirSync as mkdirSync2, readdirSync, readFileSync as readFileSync2, statSync } from "node:fs";
+import { execFileSync } from "node:child_process";
 import { basename as basename2, dirname as dirname2, isAbsolute, join as join2, relative, resolve as resolve2 } from "node:path";
 function resolveHarnessDir(startDir = process.cwd(), opts = {}) {
   const start = resolve2(startDir);
   const explicit = opts.harnessDir ?? process.env.MSTAR_HARNESS_DIR;
   if (explicit)
     return resolve2(start, explicit);
+  const boundary = resolve2(start, opts.workspaceRoot ?? defaultWorkspaceRoot(start));
   let dir = start;
   for (;; ) {
+    if (!isAtOrBelow(dir, boundary))
+      return null;
     for (const candidate of [join2(dir, ".mstar"), join2(dir, ".agents"), join2(dir, ".plans"), join2(dir, "plans")]) {
       if (isDirectory(candidate))
         return candidate;
     }
+    if (dir === boundary)
+      return null;
     const parent = dirname2(dir);
     if (parent === dir)
       return null;
     dir = parent;
   }
 }
+function defaultWorkspaceRoot(startDir) {
+  try {
+    const cdup = execFileSync("git", ["rev-parse", "--show-cdup"], {
+      cwd: startDir,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+    if (!cdup)
+      return startDir;
+    let boundary = startDir;
+    for (const segment of cdup.split(/[\\/]/)) {
+      if (segment && segment !== ".")
+        boundary = dirname2(boundary);
+    }
+    return resolve2(boundary);
+  } catch {}
+  return startDir;
+}
+function isAtOrBelow(dir, root) {
+  const rel = relative(root, dir);
+  return rel === "" || !rel.startsWith("..") && !isAbsolute(rel);
+}
 function resolveSpecsDir(harnessDir, opts = {}) {
   const harness = resolve2(harnessDir);
   const repoRoot = dirname2(harness);
@@ -158,28 +186,27 @@ function scaffoldHarness(root) {
 }
 var GITIGNORE_SNIPPET = `# Morning Star harness (.mstar/)
 # Principle: process stays local; results are shared with the team.
-# Ignored (process / coordination):
-.mstar/archived/
-.mstar/iterations/
-.mstar/plans/
-.mstar/sdd/
-.mstar/notes.json
-.mstar/status.json
-# Tracked (results): .mstar/AGENTS.md, .mstar/knowledge/, .mstar/specs/
+# Default-ignore everything under .mstar/, then re-include the tracked results.
+.mstar/**
+!.mstar/AGENTS.md
+!.mstar/knowledge/
+!.mstar/knowledge/**
+!.mstar/specs/
+!.mstar/specs/**
 `;
 var GITIGNORE_SNIPPET_AGENTS = `# Morning Star harness (.agents/) — legacy
-.agents/archived/
-.agents/iterations/
-.agents/plans/
-.agents/sdd/
-.agents/notes.json
-.agents/status.json
-# Tracked (results): .agents/AGENTS.md, .agents/knowledge/, .agents/specs/
+# Default-ignore everything under .agents/, then re-include the tracked results.
+.agents/**
+!.agents/AGENTS.md
+!.agents/knowledge/
+!.agents/knowledge/**
+!.agents/specs/
+!.agents/specs/**
 `;
 var GITIGNORE_PROCESS_ENTRIES = GITIGNORE_SNIPPET.split(`
-`).filter((line) => line.startsWith(".mstar/")).map((line) => line.trim());
+`).filter((line) => line.startsWith(".mstar/") || line.startsWith("!.mstar/")).map((line) => line.trim());
 var GITIGNORE_PROCESS_ENTRIES_AGENTS = GITIGNORE_SNIPPET_AGENTS.split(`
-`).filter((line) => line.startsWith(".agents/")).map((line) => line.trim());
+`).filter((line) => line.startsWith(".agents/") || line.startsWith("!.agents/")).map((line) => line.trim());
 function emitGitignoreSnippet(kind) {
   if (kind === "agents")
     return GITIGNORE_SNIPPET_AGENTS;
@@ -230,7 +257,7 @@ function validateGitignore(root) {
     ok: true,
     severity: "low",
     code: "gitignore.ok",
-    message: `.gitignore at ${gitignorePath} contains a complete canonical harness process-artifact ignore set (${label})`
+    message: `.gitignore at ${gitignorePath} contains a complete canonical harness ignore set — default-ignore + tracked re-includes (${label})`
   };
 }
 function detectHarnessKind(harnessDir) {
@@ -1151,7 +1178,7 @@ function techDebtRollup(docOrPath) {
   return { computed, stored, checks, overall };
 }
 // src/worktree.ts
-import { execFileSync } from "node:child_process";
+import { execFileSync as execFileSync2 } from "node:child_process";
 import { existsSync as existsSync3 } from "node:fs";
 import { isAbsolute as isAbsolute3, resolve as resolve5 } from "node:path";
 var DEFAULT_PROBE_TIMEOUT_MS = 1e4;
@@ -1174,7 +1201,7 @@ function probeBranch(worktreePath, opts) {
     return { branch: precomputed };
   const timeout = opts.timeoutMs ?? probeTimeoutMs();
   try {
-    const stdout = execFileSync(opts.gitPath ?? "git", ["-C", worktreePath, "branch", "--show-current"], {
+    const stdout = execFileSync2(opts.gitPath ?? "git", ["-C", worktreePath, "branch", "--show-current"], {
       encoding: "utf8",
       stdio: ["ignore", "pipe", "pipe"],
       timeout
@@ -1303,7 +1330,7 @@ function singleReviewSnapshot(assignments) {
   return gate(violations);
 }
 // src/sdd.ts
-import { execFileSync as execFileSync2 } from "node:child_process";
+import { execFileSync as execFileSync3 } from "node:child_process";
 import { mkdirSync as mkdirSync4, readFileSync as readFileSync4, realpathSync, statSync as statSync3, writeFileSync as writeFileSync3 } from "node:fs";
 import { basename as basename3, dirname as dirname4, isAbsolute as isAbsolute4, join as join5, resolve as resolve6 } from "node:path";
 class SddScriptError extends Error {
@@ -1331,7 +1358,7 @@ function isFile(file) {
 var GIT_CAPTURE_MAX_BYTES = 64 * 1024 * 1024;
 function gitOut(cwd, args) {
   try {
-    return execFileSync2("git", args, {
+    return execFileSync3("git", args, {
       cwd,
       encoding: "utf8",
       stdio: ["ignore", "pipe", "pipe"],
@@ -1464,7 +1491,7 @@ function reviewPackage(base, head, outFile, opts = {}) {
   const cwd = opts.cwd ?? process.cwd();
   const verifyRef = (ref, what) => {
     try {
-      execFileSync2("git", ["rev-parse", "--verify", "--quiet", ref], { cwd, stdio: ["ignore", "pipe", "pipe"] });
+      execFileSync3("git", ["rev-parse", "--verify", "--quiet", ref], { cwd, stdio: ["ignore", "pipe", "pipe"] });
     } catch {
       throw new SddScriptError(`bad ${what}: ${ref}`, 2);
     }
@@ -1484,7 +1511,7 @@ function reviewPackage(base, head, outFile, opts = {}) {
     const shortHead = gitOut(cwd, ["rev-parse", "--short", head]) ?? head;
     out = join5(sddDir, `review-${shortBase}..${shortHead}.diff`);
   }
-  const run = (args) => execFileSync2("git", args, { cwd, maxBuffer: GIT_CAPTURE_MAX_BYTES });
+  const run = (args) => execFileSync3("git", args, { cwd, maxBuffer: GIT_CAPTURE_MAX_BYTES });
   const parts = [
     Buffer.from(`# Review package: ${base}..${head}
 
@@ -1508,7 +1535,7 @@ function assertBaseSha(ref, opts = {}) {
     throw new SddScriptError(`assertBaseSha: BASE must be a commit SHA (full or prefix); got ${JSON.stringify(ref)}. ` + "Never use HEAD~1 as review BASE (multi-commit tasks truncate).", 2);
   }
   try {
-    execFileSync2("git", ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`], {
+    execFileSync3("git", ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`], {
       cwd: opts.cwd,
       stdio: ["ignore", "pipe", "pipe"]
     });
@@ -3378,6 +3405,8 @@ function detectHost(signals) {
     return "opencode";
   if (s.has("task_agent_batch") || s.has("ask") || s.has("hub"))
     return "omp";
+  if (s.has("subagent"))
+    return "dsh";
   if (s.has("AgentSwarm"))
     return "kimi";
   if (s.has("Agent") || s.has("AskUserQuestion") || s.has("EnterPlanMode") || s.has("TodoWrite"))
@@ -3401,9 +3430,10 @@ function resolveSkillRoot(host, paths) {
     case "kimi":
     case "zcode":
       return `./skills/${skill}${suffix}`;
-    case "pi":
     case "dsh":
-      return `deferred: ${host} has no plugin API in v1 — skill-root resolution lands with its adapter (roadmap §8.4)`;
+      return `$DSH_BUNDLED_SKILL_DIR/${skill}${suffix}`;
+    case "pi":
+      return `deferred: pi has no plugin API in v1 — skill-root resolution lands with its adapter (roadmap §8.4)`;
   }
 }
 // src/skill-authoring.ts

package/dist/host.d.ts

@@ -11,7 +11,10 @@
  *   resolution.
  * - `.harness/references/skill-programmatic-roadmap.md` §8.4 — the
  *   `HostAdapter` shared contract (all hooks optional; no concrete adapters
- *   in the engine; pi/dsh deferred).
+ *   in the engine; pi deferred).
+ * - `.harness/references/dsh-adapter-roadmap.md` §4 D5 (this iteration) —
+ *   the dsh detection row + skill-root form; mirror text lands in the
+ *   mstar-host skill when this module is upstreamed.
  *
  * UX judgment (ambiguous-host fallback reasoning, plan-mode bridges) stays
  * prompt — this module only turns tool shapes into a host id.
@@ -19,18 +22,19 @@
 import type { GateResult, ValidationResult } from "./core.js";
 import type { AssignmentFields } from "./dispatch.js";
 import type { IntegrationMergeLease } from "./lease.js";
-/** All hosts the engine knows about (roadmap §8.4 host union). `pi` and
- * `dsh` have no plugin API in v1 — they appear in the union (and in
- * `HostAdapter.host`) but are never detected and get no adapters. */
+/** All hosts the engine knows about (roadmap §8.4 host union). `pi` has no
+ * plugin API in v1 — it appears in the union (and in `HostAdapter.host`) but
+ * is never detected and gets no adapter. `dsh` is detected and resolved
+ * (roadmap §4 D5, this iteration); its adapter ships in the dsh plugin. */
 export type HostId = "opencode" | "omp" | "pi" | "dsh" | "cursor" | "codex" | "kimi" | "zcode";
-/** Result of `detectHost`: one of the six known hosts or `ambiguous`
+/** Result of `detectHost`: one of the seven known hosts or `ambiguous`
  * (prompt judgment then applies per mstar-host). */
-export type DetectResult = "opencode" | "omp" | "cursor" | "codex" | "kimi" | "zcode" | "ambiguous";
+export type DetectResult = "opencode" | "omp" | "dsh" | "cursor" | "codex" | "kimi" | "zcode" | "ambiguous";
 /** Tool-shape signal tokens accepted by `detectHost`, derived from the
  * mstar-host detection table. Plan-mode extras (CreatePlan/SwitchMode) and
  * Browser-plugin tools are documented in the table but are not part of the
  * v1 signal enum. */
-export type ToolSignal = "subagent_type" | "question" | "task_subagent" | "task_agent_batch" | "ask" | "hub" | "Agent" | "AgentSwarm" | "AskUserQuestion" | "EnterPlanMode" | "TodoWrite" | "plan_slash" | "goal" | "functions.*" | "tool_search";
+export type ToolSignal = "subagent_type" | "question" | "task_subagent" | "task_agent_batch" | "ask" | "hub" | "subagent" | "Agent" | "AgentSwarm" | "AskUserQuestion" | "EnterPlanMode" | "TodoWrite" | "plan_slash" | "goal" | "functions.*" | "tool_search";
 /**
  * Detect the active host from session tool shapes, per the ordered
  * mstar-host table (ported verbatim):
@@ -40,14 +44,19 @@ export type ToolSignal = "subagent_type" | "question" | "task_subagent" | "task_
  * | `subagent_type` (Task param; plan mode + CreatePlan/SwitchMode) | cursor |
  * | `question`, or `task_subagent` (task tool, singular subagent, no batch) | opencode |
  * | `task_agent_batch` (task tool, agent/tasks[] batch), `ask`, `hub` | omp |
+ * | `subagent` (dsh's model-facing delegation tool) | dsh |
  * | `Agent`/`AskUserQuestion`/`EnterPlanMode` + `AgentSwarm` (Kimi-only) | kimi |
  * | `Agent`/`AskUserQuestion`/`EnterPlanMode`/`TodoWrite`, no `AgentSwarm` | zcode |
  * | `/plan`, `/goal`; Goal tools; `functions.*` namespaces; `tool_search` | codex |
  *
- * Order matters: cursor → opencode → omp → kimi → zcode → codex — the
- * sharpest Task-based split is `subagent_type` (Cursor) vs `subagent`
- * (OpenCode) vs `agent`/`tasks[]` (omp). Still ambiguous → `"ambiguous"`
- * (prompt judgment stays in the skill).
+ * Order matters: cursor → opencode → omp → dsh → kimi → zcode → codex — the
+ * sharpest Task-based split is `subagent_type` (Cursor) vs `task_subagent`
+ * (OpenCode) vs `agent`/`tasks[]` (omp); dsh's `subagent` tool (roadmap §4
+ * D5) collides with no other row, so it sits with the agent-tool hosts.
+ * (`mstar-host` skill prose still says colloquial `subagent` for OpenCode —
+ * disambiguate it to `task_subagent` in the same upstream PR that carries
+ * this row, together with the CLI `HOST_SIGNALS` list.)
+ * Still ambiguous → `"ambiguous"` (prompt judgment stays in the skill).
  */
 export declare function detectHost(signals: readonly ToolSignal[]): DetectResult;
 /** Skill name + optional skill-relative path for skill-root resolution. */
@@ -69,7 +78,8 @@ export type SkillRootPaths = {
  * | codex | `skills/<name>[/<rel>]` (plugin-mounted; project command skills under `.agents/skills/<name>/`) |
  * | opencode | `harness-skills/<name>[/<rel>]` (package-internal via `@mstar-harness/opencode` — never `process.cwd()/skills/`) |
  * | kimi / zcode | `./skills/<name>[/<rel>]` (plugin mount from the installed plugin root) |
- * | pi / dsh | deferred — no plugin API in v1 (roadmap §8.4) |
+ * | dsh | `$DSH_BUNDLED_SKILL_DIR/<name>[/<rel>]` (skill-local bundled root — dsh-skill-local `bundledSkillDir` default; the single canonical mount per roadmap D6. Frozen this iteration; local dev mounts the mirror `skills/` via `customSkillDirs` instead, but the canonical published form stays the bundled root) |
+ * | pi | deferred — no plugin API in v1 (roadmap §8.4) |
  */
 export declare function resolveSkillRoot(host: HostId, paths: SkillRootPaths): string;
 /**
@@ -79,8 +89,8 @@ export declare function resolveSkillRoot(host: HostId, paths: SkillRootPaths): s
  * rule: skill text remains authoritative; the engine only returns results
  * the caller chooses to honor). `log` is required — adapters must be able to
  * report. No concrete adapters ship in the engine: opencode binds via its
- * own plugin code, omp via the command layer; pi/dsh adapters are deferred
- * until their plugin APIs land.
+ * own plugin code, omp via the command layer, dsh via the dsh plugin (this
+ * iteration); pi stays deferred until its plugin API lands.
  */
 export interface HostAdapter {
     host: "opencode" | "omp" | "pi" | "dsh" | "cursor" | "codex" | "kimi" | "zcode";

package/dist/path.d.ts

@@ -10,15 +10,32 @@ export type ResolveHarnessDirOptions = {
      * (the caller may scaffold it).
      */
     harnessDir?: string;
+    /**
+     * Workspace-root stop boundary (roadmap §7c / plan
+     * 20260810-harness-root-boundary). The upward probe keeps walking only
+     * while `dir` is at or below this root — a harness dir above it is never
+     * returned (the `~/.mstar` global-collision defect is the special case).
+     * Resolved against `startDir` when relative. When omitted, the default
+     * boundary is the git top-level of `startDir` (sync `git rev-parse
+     * --show-cdup`; on failure / non-git start it falls back to
+     * `startDir` itself — a non-git start probes only itself, never upward;
+     * deliberate tightening). The boundary is an explicit caller value: the
+     * engine git-probes only for this default resolution, never during the
+     * walk.
+     */
+    workspaceRoot?: string;
 };
 /**
  * Resolve `{HARNESS_DIR}` per plan-conventions § {HARNESS_DIR} 解析顺序
  * (find-first-stop): `.mstar/` → `.agents/` → `.plans/`/`plans/`, walking up
- * from `startDir`. Harness candidates are dir-existence (the empty-dir rule
- * applies to `{SPECS_DIR}` only). An explicit override via `opts.harnessDir`
- * or `MSTAR_HARNESS_DIR` wins over probing.
+ * from `startDir` but NEVER above the workspace root (`opts.workspaceRoot`,
+ * default = git top-level of `startDir`). Harness candidates are
+ * dir-existence (the empty-dir rule applies to `{SPECS_DIR}` only). An
+ * explicit override via `opts.harnessDir` or `MSTAR_HARNESS_DIR` wins over
+ * probing and short-circuits before any boundary logic.
  *
- * Returns the absolute harness dir, or `null` when no candidate exists.
+ * Returns the absolute harness dir, or `null` when no candidate exists
+ * within the workspace boundary.
  */
 export declare function resolveHarnessDir(startDir?: string, opts?: ResolveHarnessDirOptions): string | null;
 /**
@@ -86,15 +103,17 @@ export declare function scaffoldHarness(root: string): string;
 export type HarnessKind = "mstar" | "agents";
 /**
  * Emit the canonical `.gitignore` snippet for `kind` (plan-conventions
- * § Git 跟踪策略): the process-artifact ignore set (`archived/`,
- * `iterations/`, `plans/`, `sdd/`, `notes.json`, `status.json` under the
- * harness dir) with the tracked/results note. When the kind is unknown
- * (omitted), both snippets are emitted so either fence can be applied.
+ * § Git 跟踪策略): default-ignore the whole harness dir (`<dir>/**`) and
+ * re-include only the tracked results (AGENTS.md, knowledge/, specs/).
+ * When the kind is unknown (omitted), both snippets are emitted so either
+ * fence can be applied.
  */
 export declare function emitGitignoreSnippet(kind?: HarnessKind): string;
 /**
  * Validate that `<root>/.gitignore` contains a complete canonical
- * process-artifact ignore set (plan-conventions § Git 跟踪策略). Rule
+ * harness ignore set — default-ignore `<dir>/**` plus the tracked
+ * re-includes (AGENTS.md, knowledge/, specs/) per plan-conventions
+ * § Git 跟踪策略. Rule
  * (chosen alignment): the gate passes when the repo's .gitignore holds ONE
  * complete set for the DETECTED harness kind — `.mstar/` for a `.mstar`
  * harness, `.agents/` for a legacy `.agents` harness; layouts without a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mstar-harness/engine",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Morning Star Harness Workflow Engine — deterministic workflow enforcement library (path, status, lease, dispatch, sdd, iteration, lint gates).",
   "license": "MIT",
   "repository": {