coding-agent-harness 1.0.7 → 1.1.0

package/dist/check-import-graph.mjs

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-// @ts-nocheck
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -105,7 +104,7 @@ export function checkImportGraph({ repoRoot = defaultRepoRoot, expectNodes, expe
     const graph = buildImportGraph({ repoRoot });
     const violations = [];
     for (const edge of graph.unresolvedEdges) {
-        violations.push({ code: "unresolved-local-edge", ...edge });
+        violations.push({ ...edge, code: "unresolved-local-edge" });
     }
     for (const cycle of graph.cycles) {
         violations.push({
@@ -115,23 +114,25 @@ export function checkImportGraph({ repoRoot = defaultRepoRoot, expectNodes, expe
         });
     }
     for (const edge of graph.runtimeMjsToTsEdges) {
-        violations.push({ code: "mjs-imports-ts", ...edge });
+        violations.push({ ...edge, code: "mjs-imports-ts" });
     }
     for (const edge of graph.typesValueImports) {
-        violations.push({ code: "types-value-import", ...edge });
+        violations.push({ ...edge, code: "types-value-import" });
     }
     const barrels = graph.nodes.filter((node) => node.path === "scripts/lib/harness-core.mts" || node.path === "scripts/lib/harness-core.mjs");
-    for (const edge of barrels.flatMap((barrel) => barrel.imports || [])) {
-        if (edge.kind !== "export" || !edge.target)
-            continue;
-        const target = graph.nodes.find((node) => node.path === edge.target);
-        if (!target?.barrelReachable) {
-            violations.push({
-                code: "barrel-target-not-reachable",
-                file: barrel.path,
-                target: edge.target,
-                message: `${edge.target} is exported by harness-core but is not marked barrel reachable`,
-            });
+    for (const barrel of barrels) {
+        for (const edge of barrel.imports || []) {
+            if (edge.kind !== "export" || !edge.target)
+                continue;
+            const target = graph.nodes.find((node) => node.path === edge.target);
+            if (!target?.barrelReachable) {
+                violations.push({
+                    code: "barrel-target-not-reachable",
+                    file: barrel.path,
+                    target: edge.target,
+                    message: `${edge.target} is exported by harness-core but is not marked barrel reachable`,
+                });
+            }
         }
     }
     if (expectNodes !== undefined && graph.summary.fileCount !== expectNodes) {
@@ -344,6 +345,8 @@ function markReachable(nodesByPath, startPath, field) {
     const seen = new Set();
     while (stack.length > 0) {
         const current = stack.pop();
+        if (!current)
+            continue;
         if (seen.has(current))
             continue;
         seen.add(current);
@@ -385,10 +388,10 @@ function findCycles(nodesByPath) {
         for (const target of adjacency(nodesByPath, file)) {
             if (!indexByPath.has(target)) {
                 strongConnect(target);
-                lowlinkByPath.set(file, Math.min(lowlinkByPath.get(file), lowlinkByPath.get(target)));
+                lowlinkByPath.set(file, Math.min(lowlinkByPath.get(file) ?? 0, lowlinkByPath.get(target) ?? 0));
             }
             else if (onStack.has(target)) {
-                lowlinkByPath.set(file, Math.min(lowlinkByPath.get(file), indexByPath.get(target)));
+                lowlinkByPath.set(file, Math.min(lowlinkByPath.get(file) ?? 0, indexByPath.get(target) ?? 0));
             }
         }
         if (lowlinkByPath.get(file) === indexByPath.get(file)) {
@@ -396,10 +399,12 @@ function findCycles(nodesByPath) {
             let current;
             do {
                 current = stack.pop();
+                if (!current)
+                    break;
                 onStack.delete(current);
                 component.push(current);
             } while (current !== file);
-            if (component.length > 1 || hasSelfLoop(nodesByPath, component[0]))
+            if (component.length > 1 || hasSelfLoop(nodesByPath, component[0] ?? ""))
                 cycles.push(component.sort());
         }
     }
@@ -407,13 +412,13 @@ function findCycles(nodesByPath) {
         if (!indexByPath.has(file))
             strongConnect(file);
     }
-    return cycles.sort((left, right) => left[0].localeCompare(right[0]));
+    return cycles.sort((left, right) => (left[0] ?? "").localeCompare(right[0] ?? ""));
 }
 function assignLayers(nodesByPath, cycleNodeSet) {
     const memo = new Map();
     function layerFor(file, visiting = new Set()) {
         if (memo.has(file))
-            return memo.get(file);
+            return memo.get(file) ?? null;
         if (cycleNodeSet.has(file) || visiting.has(file)) {
             memo.set(file, null);
             return null;
@@ -435,7 +440,7 @@ function assignLayers(nodesByPath, cycleNodeSet) {
     }
 }
 function adjacency(nodesByPath, file) {
-    return (nodesByPath.get(file)?.imports || []).map((imported) => imported.target).filter((target) => target && nodesByPath.has(target));
+    return (nodesByPath.get(file)?.imports || []).map((imported) => imported.target).filter((target) => Boolean(target && nodesByPath.has(target)));
 }
 function hasSelfLoop(nodesByPath, file) {
     return adjacency(nodesByPath, file).includes(file);
@@ -460,17 +465,29 @@ function parseCliArgs(argv) {
             args.check = true;
         else if (arg === "--json")
             args.json = true;
-        else if (arg === "--out")
-            args.out = argv[++index];
-        else if (arg === "--expect-nodes")
-            args.expectNodes = Number(argv[++index]);
-        else if (arg === "--expect-edges")
-            args.expectEdges = Number(argv[++index]);
+        else if (arg === "--out") {
+            args.out = requireValue(argv, index, arg);
+            index += 1;
+        }
+        else if (arg === "--expect-nodes") {
+            args.expectNodes = Number(requireValue(argv, index, arg));
+            index += 1;
+        }
+        else if (arg === "--expect-edges") {
+            args.expectEdges = Number(requireValue(argv, index, arg));
+            index += 1;
+        }
         else
             throw new Error(`Unknown argument: ${arg}`);
     }
     return args;
 }
+function requireValue(argv, index, option) {
+    const value = argv[index + 1];
+    if (!value)
+        throw new Error(`${option} requires a value`);
+    return value;
+}
 function writeOutput({ graph, args }) {
     if (args.out) {
         fs.mkdirSync(path.dirname(path.resolve(args.out)), { recursive: true });

package/dist/check-lite-forbidden-surfaces.mjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const defaultRepoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+function parseArgs(argv) {
+    let repoRoot = defaultRepoRoot;
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === "--repo-root") {
+            const value = argv[index + 1];
+            if (!value)
+                throw new Error("--repo-root requires a value");
+            repoRoot = path.resolve(value);
+            index += 1;
+            continue;
+        }
+        throw new Error(`Unknown argument: ${arg}`);
+    }
+    return { repoRoot };
+}
+export function checkLiteForbiddenSurfaces(repoRoot = defaultRepoRoot) {
+    const forbiddenPath = path.join(repoRoot, "docs-release/architecture/document-contract-kernel/products/lite-forbidden-surfaces.txt");
+    const patterns = readForbiddenPatterns(forbiddenPath);
+    const scannedFiles = collectLiteProductFiles(repoRoot);
+    const violations = [];
+    for (const relativeFile of scannedFiles) {
+        const absoluteFile = path.join(repoRoot, relativeFile);
+        const lines = fs.readFileSync(absoluteFile, "utf8").split(/\r?\n/);
+        for (const [lineIndex, line] of lines.entries()) {
+            for (const pattern of patterns) {
+                pattern.pattern.lastIndex = 0;
+                if (pattern.pattern.test(line)) {
+                    violations.push({
+                        file: relativeFile,
+                        line: lineIndex + 1,
+                        pattern: pattern.source,
+                        text: line.trim(),
+                    });
+                }
+            }
+        }
+    }
+    return { ok: violations.length === 0, violations, scannedFiles };
+}
+function readForbiddenPatterns(forbiddenPath) {
+    if (!fs.existsSync(forbiddenPath)) {
+        throw new Error(`Missing Lite forbidden-surface list: ${path.relative(process.cwd(), forbiddenPath)}`);
+    }
+    const lines = fs.readFileSync(forbiddenPath, "utf8").split(/\r?\n/);
+    return lines
+        .map((line) => line.trim())
+        .filter((line) => line && !line.startsWith("#"))
+        .map((line) => {
+        if (line.startsWith("literal:")) {
+            const literal = line.slice("literal:".length);
+            return { source: line, pattern: new RegExp(escapeRegExp(literal), "i") };
+        }
+        if (line.startsWith("regex:")) {
+            const source = line.slice("regex:".length);
+            return { source: line, pattern: new RegExp(source, "i") };
+        }
+        return { source: line, pattern: new RegExp(escapeRegExp(line), "i") };
+    });
+}
+function collectLiteProductFiles(repoRoot) {
+    const files = new Set();
+    const explicitFiles = [
+        "docs-release/architecture/document-contract-kernel/products/lite-skill-overlay.md",
+        "skills/coding-agent-harness-lite/SKILL.md",
+    ];
+    for (const relativeFile of explicitFiles) {
+        if (fs.existsSync(path.join(repoRoot, relativeFile)))
+            files.add(relativeFile);
+    }
+    for (const relativeDir of ["skill-sources/products/lite", "skill-sources/document-kernel/products/lite"]) {
+        const absoluteDir = path.join(repoRoot, relativeDir);
+        if (!fs.existsSync(absoluteDir))
+            continue;
+        for (const relativeFile of walkTextFiles(absoluteDir, repoRoot))
+            files.add(relativeFile);
+    }
+    return [...files].sort();
+}
+function walkTextFiles(current, repoRoot) {
+    const stat = fs.lstatSync(current);
+    if (stat.isSymbolicLink())
+        return [];
+    if (stat.isFile()) {
+        return /\.(md|txt|template)$/.test(current) ? [toPosix(path.relative(repoRoot, current))] : [];
+    }
+    const files = [];
+    for (const entry of fs.readdirSync(current)) {
+        files.push(...walkTextFiles(path.join(current, entry), repoRoot));
+    }
+    return files;
+}
+function toPosix(value) {
+    return value.split(path.sep).join("/");
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+    try {
+        const { repoRoot } = parseArgs(process.argv.slice(2));
+        const result = checkLiteForbiddenSurfaces(repoRoot);
+        if (!result.ok) {
+            console.error([
+                "Lite forbidden-surface check failed:",
+                ...result.violations.map((violation) => `${violation.file}:${violation.line}: ${violation.pattern}: ${violation.text}`),
+            ].join("\n"));
+            process.exit(1);
+        }
+        console.log(`Lite forbidden-surface check passed (${result.scannedFiles.length} files scanned)`);
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }
+}

package/dist/check-no-ts-nocheck.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const defaultRepoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const sourceRoots = ["scripts", "tests"];
+const tsNocheckPattern = new RegExp(String.raw `^\s*//\s*` + "@ts" + String.raw `-nocheck\b`);
+export function checkNoTsNocheck({ repoRoot = defaultRepoRoot, allowlistPath = path.join(repoRoot, "scripts/ts-nocheck-allowlist.json"), } = {}) {
+    const files = collectTypeScriptFiles(repoRoot);
+    const allowlist = readAllowlist(allowlistPath);
+    const violations = [];
+    const observed = new Set();
+    for (const file of files) {
+        const absolutePath = path.join(repoRoot, file);
+        const lines = fs.readFileSync(absolutePath, "utf8").split(/\r?\n/);
+        const lineIndex = lines.findIndex((line) => tsNocheckPattern.test(line));
+        if (lineIndex === -1)
+            continue;
+        observed.add(file);
+        if (!allowlist.has(file)) {
+            violations.push({
+                code: "unlisted-ts-nocheck",
+                file,
+                line: lineIndex + 1,
+                message: `${file}:${lineIndex + 1} has ${"@ts"}-nocheck but is not in scripts/ts-nocheck-allowlist.json`,
+            });
+        }
+    }
+    for (const file of allowlist) {
+        if (!observed.has(file)) {
+            violations.push({
+                code: "stale-ts-nocheck-allowlist",
+                file,
+                message: `${file} is listed in scripts/ts-nocheck-allowlist.json but no longer has ${"@ts"}-nocheck`,
+            });
+        }
+    }
+    return { ok: violations.length === 0, violations };
+}
+function collectTypeScriptFiles(repoRoot) {
+    const files = [];
+    for (const root of sourceRoots) {
+        const absoluteRoot = path.join(repoRoot, root);
+        if (!fs.existsSync(absoluteRoot))
+            continue;
+        walk(absoluteRoot, files, repoRoot);
+    }
+    return files.sort();
+}
+function walk(current, files, repoRoot) {
+    const stat = fs.lstatSync(current);
+    if (stat.isSymbolicLink())
+        return;
+    if (stat.isDirectory()) {
+        const name = path.basename(current);
+        if (name === "node_modules" || name === ".worktrees" || name === "tmp")
+            return;
+        for (const entry of fs.readdirSync(current))
+            walk(path.join(current, entry), files, repoRoot);
+        return;
+    }
+    if (stat.isFile() && /\.(mts|ts)$/.test(current)) {
+        files.push(path.relative(repoRoot, current).split(path.sep).join("/"));
+    }
+}
+function readAllowlist(allowlistPath) {
+    if (!allowlistPath || !fs.existsSync(allowlistPath))
+        return new Set();
+    const parsed = JSON.parse(fs.readFileSync(allowlistPath, "utf8"));
+    const files = normalizeAllowlistFiles(parsed);
+    return new Set(files);
+}
+function normalizeAllowlistFiles(parsed) {
+    if (Array.isArray(parsed))
+        return parsed.filter((value) => typeof value === "string");
+    if (typeof parsed !== "object" || parsed === null)
+        return [];
+    const files = parsed.files;
+    return Array.isArray(files) ? files.filter((value) => typeof value === "string") : [];
+}
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+    const result = checkNoTsNocheck();
+    if (!result.ok) {
+        console.error(result.violations.map((violation) => violation.message).join("\n"));
+        process.exit(1);
+    }
+    console.log(`No ${"@ts"}-nocheck gate passed`);
+}

package/dist/check-runtime-emit.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";
@@ -75,11 +74,19 @@ export function checkRuntimeEmitContract({ projectRoot = defaultRepoRoot, config
     };
 }
 function runTypeScriptEmit({ projectRoot, configPath, outDir }) {
-    return spawnSync("npm", ["exec", "--yes", "--package", `typescript@${typescriptVersion}`, "--", "tsc", "-p", configPath, "--outDir", outDir, "--noCheck"], {
+    const npmArgs = ["exec", "--yes", "--package", `typescript@${typescriptVersion}`, "--", "tsc", "-p", configPath, "--outDir", outDir, "--noCheck"];
+    const npmCommand = resolveNpmCommand(npmArgs);
+    return spawnSync(npmCommand.command, npmCommand.args, {
         cwd: projectRoot,
         encoding: "utf8",
     });
 }
+function resolveNpmCommand(npmArgs) {
+    const npmExecPath = process.env.npm_execpath;
+    if (npmExecPath)
+        return { command: process.execPath, args: [npmExecPath, ...npmArgs] };
+    return { command: process.platform === "win32" ? "npm.cmd" : "npm", args: npmArgs };
+}
 function compareDirectories({ expectedDir, actualDir, violations }) {
     const expectedFiles = collectFiles(expectedDir).filter((file) => file.endsWith(".mjs")).sort();
     const actualFiles = collectFiles(actualDir).filter((file) => file.endsWith(".mjs")).sort();
@@ -129,7 +136,7 @@ function collectFiles(directory) {
         walk(directory, files, () => true);
     return files.sort();
 }
-function walk(current, files, predicate, sourceRoot) {
+function walk(current, files, predicate, sourceRoot = "") {
     const stat = fs.lstatSync(current);
     if (stat.isSymbolicLink())
         return;

package/dist/check-type-boundaries.mjs

@@ -1,31 +1,48 @@
 #!/usr/bin/env node
-// @ts-nocheck
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 const defaultRepoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const sourceRoots = ["scripts", "tests"];
 const importPattern = /\b(import|export)\s+(type\s+)?(?:[^'"]*?\s+from\s+)?["']([^"']+)["']|\bimport\s*\(\s*["']([^"']+)["']\s*\)/g;
-const tsEscapePattern = /@(ts-ignore|ts-expect-error)\b|(?:^|[^A-Za-z0-9_$])(?:as\s+any|:\s*any\b)/;
-export function checkTypeBoundaries({ repoRoot = defaultRepoRoot } = {}) {
+const tsEscapePattern = /@(ts-ignore|ts-expect-error|ts-nocheck)\b|\bas\s+unknown\s+as\b|<[^>\n]*\bany\b[^>\n]*>|(?:^|[^A-Za-z0-9_$])(?:as\s+any|:\s*any\b)/;
+const crossLineUnknownCastPattern = /\bas\s+unknown\s+as\b/;
+export function checkTypeBoundaries({ repoRoot = defaultRepoRoot, escapeAllowlistPath = path.join(repoRoot, "scripts/type-escape-allowlist.json"), } = {}) {
     const files = collectSourceFiles(repoRoot);
     const violations = [];
+    const escapeAllowlist = readEscapeAllowlist(escapeAllowlistPath);
+    const observedEscapes = new Set();
     for (const file of files) {
         const absolutePath = path.join(repoRoot, file);
         const content = fs.readFileSync(absolutePath, "utf8");
         const imports = parseImports(content);
-        if (file.endsWith(".ts")) {
+        if (file.endsWith(".ts") || file.endsWith(".mts")) {
             const lines = content.split(/\r?\n/);
             for (const [index, line] of lines.entries()) {
                 if (tsEscapePattern.test(line)) {
-                    violations.push({
+                    const violation = {
                         code: "ts-escape-hatch",
                         file,
                         line: index + 1,
                         message: `${file}:${index + 1} uses a TypeScript escape hatch that requires review`,
-                    });
+                    };
+                    observedEscapes.add(escapeKey(violation));
+                    if (!isEscapeAllowed(escapeAllowlist, violation))
+                        violations.push(violation);
                 }
             }
+            if (crossLineUnknownCastPattern.test(content) && !lines.some((line) => /\bas\s+unknown\s+as\b/.test(line))) {
+                const line = lineForOffset(content, content.search(crossLineUnknownCastPattern));
+                const violation = {
+                    code: "ts-escape-hatch",
+                    file,
+                    line,
+                    message: `${file}:${line} uses a cross-line TypeScript escape hatch that requires review`,
+                };
+                observedEscapes.add(escapeKey(violation));
+                if (!isEscapeAllowed(escapeAllowlist, violation))
+                    violations.push(violation);
+            }
         }
         for (const imported of imports) {
             if (!isLocalSpecifier(imported.specifier))
@@ -49,6 +66,16 @@ export function checkTypeBoundaries({ repoRoot = defaultRepoRoot } = {}) {
             }
         }
     }
+    for (const allowed of escapeAllowlist.values()) {
+        if (observedEscapes.has(allowed.key))
+            continue;
+        violations.push({
+            code: "stale-ts-escape-allowlist",
+            file: allowed.file,
+            line: allowed.line,
+            message: `${allowed.file}:${allowed.line} is listed in ${path.relative(repoRoot, escapeAllowlistPath)} but no matching TypeScript escape hatch was found`,
+        });
+    }
     return { ok: violations.length === 0, violations };
 }
 function collectSourceFiles(repoRoot) {
@@ -83,7 +110,7 @@ function parseImports(content) {
         imports.push({
             kind: match[1] || "import",
             typeOnly: match[2] === "type ",
-            specifier: match[3] || match[4],
+            specifier: match[3] || match[4] || "",
         });
     }
     return imports;
@@ -127,7 +154,39 @@ function hasTypeScriptSourceExtension(filePath) {
     return typeof filePath === "string" && /\.(mts|ts)$/.test(filePath);
 }
 function isTypeOnlyTypeScriptImport(file, imported) {
-    return file.endsWith(".ts") && imported.kind === "import" && imported.typeOnly;
+    return (file.endsWith(".ts") || file.endsWith(".mts")) && imported.kind === "import" && imported.typeOnly;
+}
+function readEscapeAllowlist(allowlistPath) {
+    if (!allowlistPath || !fs.existsSync(allowlistPath))
+        return new Map();
+    const parsed = JSON.parse(fs.readFileSync(allowlistPath, "utf8"));
+    const entries = Array.isArray(parsed) ? parsed : parsed.escapes || [];
+    return new Map(entries.map((entry) => {
+        if (typeof entry === "string") {
+            return [
+                entry,
+                {
+                    key: entry,
+                    file: entry.split(":")[0] || entry,
+                    line: Number.parseInt(entry.split(":")[1] || "", 10) || undefined,
+                    code: entry.split(":")[2] || "ts-escape-hatch",
+                },
+            ];
+        }
+        const key = `${entry.file}:${entry.line}:${entry.code || "ts-escape-hatch"}`;
+        return [key, { key, file: entry.file, line: entry.line, code: entry.code || "ts-escape-hatch" }];
+    }));
+}
+function isEscapeAllowed(allowlist, violation) {
+    return allowlist.has(escapeKey(violation)) || allowlist.has(`${violation.file}:${violation.line}`);
+}
+function escapeKey(violation) {
+    return `${violation.file}:${violation.line}:${violation.code}`;
+}
+function lineForOffset(content, offset) {
+    if (offset < 0)
+        return 1;
+    return content.slice(0, offset).split(/\r?\n/).length;
 }
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
     const result = checkTypeBoundaries();

package/dist/commands/dashboard-command.mjs

@@ -1,9 +1,31 @@
-// @ts-nocheck
 // Dashboard command parsing stays behavior-first until command handler types are modeled.
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { normalizeTarget, serveDashboardWorkbench, writeDashboardFolder, writeDashboardSingleFile, } from "../lib/harness-core.mjs";
 import { dashboardWatchRoots } from "../lib/harness-paths.mjs";
+export async function runDevDashboardCommand({ takeFlag, takeOption, targetArg }) {
+    const open = !takeFlag("--no-open");
+    const outDir = takeOption("--out-dir", "");
+    const host = takeOption("--host", "127.0.0.1");
+    const port = Number(takeOption("--port", "0"));
+    const localeOverride = takeOption("--locale", "");
+    const target = targetArg();
+    const usesDefaultOutDir = !outDir;
+    const dashboardOutDir = outDir || defaultDevOutDir(target);
+    const opts = {
+        ...(localeOverride ? { localeOverride } : {}),
+        recoverGeneratedDashboard: usesDefaultOutDir,
+        replaceExistingDashboardOutput: usesDefaultOutDir,
+    };
+    try {
+        await serveDashboardWorkbench(dashboardOutDir, target, { ...opts, host, port, autoRefresh: true, open, label: "harness dev" });
+    }
+    catch (error) {
+        console.error(errorMessage(error));
+        process.exit(1);
+    }
+}
 export async function runDashboardCommand({ takeFlag, takeOption, targetArg }) {
     const watch = takeFlag("--watch");
     const workbench = takeFlag("--workbench");
@@ -19,11 +41,11 @@ export async function runDashboardCommand({ takeFlag, takeOption, targetArg }) {
             process.exit(2);
         }
         try {
-            assertV2DashboardTarget(targetArg());
-            await serveDashboardWorkbench(outDir, targetArg(), { ...opts, host, port });
+            requireV2DashboardTarget(targetArg());
+            await serveDashboardWorkbench(outDir, targetArg(), { ...opts, host, port: Number(port) });
         }
         catch (error) {
-            console.error(error.message);
+            console.error(errorMessage(error));
             process.exit(1);
         }
     }
@@ -33,28 +55,29 @@ export async function runDashboardCommand({ takeFlag, takeOption, targetArg }) {
             process.exit(2);
         }
         const target = targetArg();
-        assertV2DashboardTarget(target);
-        const normalizedTarget = normalizeTarget(target);
-        const watchRoots = dashboardWatchRoots(normalizedTarget.harness);
+        const harnessPaths = requireV2DashboardTarget(target);
+        const watchRoots = dashboardWatchRoots(harnessPaths);
         const regenerate = () => {
             try {
                 console.log(writeDashboardFolder(outDir, target, opts));
                 console.log(`dashboard regenerated: ${new Date().toISOString()}`);
             }
             catch (error) {
-                console.error(`dashboard regeneration failed: ${error.message}`);
+                console.error(`dashboard regeneration failed: ${errorMessage(error)}`);
             }
         };
         regenerate();
         let timer = null;
         const watchers = watchRoots.map((watchRoot) => fs.watch(watchRoot, { recursive: true }, () => {
-            clearTimeout(timer);
+            if (timer)
+                clearTimeout(timer);
             timer = setTimeout(regenerate, 300);
         }));
         const close = () => {
             for (const watcher of watchers)
                 watcher.close();
-            clearTimeout(timer);
+            if (timer)
+                clearTimeout(timer);
             process.exit(0);
         };
         process.on("SIGINT", close);
@@ -62,7 +85,7 @@ export async function runDashboardCommand({ takeFlag, takeOption, targetArg }) {
         console.log(`watching ${watchRoots.join(", ")}`);
         await new Promise(() => { });
     }
-    assertV2DashboardTarget(targetArg());
+    requireV2DashboardTarget(targetArg());
     if (outDir) {
         console.log(writeDashboardFolder(outDir, targetArg(), opts));
     }
@@ -71,10 +94,25 @@ export async function runDashboardCommand({ takeFlag, takeOption, targetArg }) {
     }
     process.exit(0);
 }
-function assertV2DashboardTarget(target) {
+function requireV2DashboardTarget(target) {
     const normalizedTarget = normalizeTarget(target);
-    if (normalizedTarget.harness?.version === 2)
-        return;
+    const harnessPaths = readV2HarnessPaths(normalizedTarget);
+    if (harnessPaths)
+        return harnessPaths;
     console.error("dashboard requires v2 harness structure; run `harness migrate-structure --plan` then `harness migrate-structure --apply`");
     process.exit(1);
 }
+function defaultDevOutDir(targetInput) {
+    const target = path.resolve(targetInput || ".");
+    return path.join(os.tmpdir(), "coding-agent-harness-dev", `${path.basename(target) || "project"}-${Buffer.from(target).toString("hex").slice(0, 16)}`);
+}
+function readV2HarnessPaths(target) {
+    const harness = target.harness;
+    return isRecord(harness) && harness.version === 2 ? harness : null;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}