coding-agent-harness 1.0.4 → 1.0.5

package/scripts/lib/preset-registry.mjs

@@ -1,23 +1,34 @@
 import fs from "node:fs";
 import path from "node:path";
+import os from "node:os";
 import crypto from "node:crypto";
+import zlib from "node:zlib";
 import { builtinPresetRoot, projectPresetRoot, repoRoot, toPosix, userPresetRoot, userPresetRootForHome } from "./core-shared.mjs";
 
 const allowedEntrypoints = new Set(["newTask", "plan", "scaffold", "check"]);
 const allowedEntrypointTypes = new Set(["template", "script", "check"]);
 const allowedEvidenceTypes = new Set(["text", "json", "input-json", "preset-audit", "preset-manifest", "write-scope", "migration-verify", "migration-ledger", "dashboard-hash", "target-git-status", "target-commit", "harness-version", "generated-at"]);
+const allowedNewTaskTemplateKeys = new Set(["taskPlanAppend", "executionStrategyAppend", "visualMapAppend", "findingsSeed", "reviewSeed", "prompt"]);
+const maxPresetArchiveBytes = 25 * 1024 * 1024;
+const maxPresetArchiveUncompressedBytes = 50 * 1024 * 1024;
+const maxPresetArchiveEntries = 500;
 
 export function listPresetPackages({ targetInput = "", home = "" } = {}) {
-  const seen = new Set();
+  return listPresetPackageLayers({ targetInput, home }).filter((preset) => preset.effective);
+}
+
+export function listPresetPackageLayers({ targetInput = "", home = "" } = {}) {
+  const effectiveIds = new Set();
   const presets = [];
   for (const { root, source } of presetSearchRoots({ targetInput, home })) {
     if (!fs.existsSync(root)) continue;
     for (const entry of fs.readdirSync(root, { withFileTypes: true }).filter((item) => item.isDirectory()).sort((a, b) => a.name.localeCompare(b.name))) {
       const id = tryNormalizePresetId(entry.name);
       if (!id) continue;
-      if (seen.has(id)) continue;
-      seen.add(id);
-      presets.push(readPresetPackage(id, { targetInput, home }));
+      const preset = readPresetPackageFromPath(path.join(root, id), source);
+      const effective = !effectiveIds.has(preset.id);
+      if (effective) effectiveIds.add(preset.id);
+      presets.push({ ...preset, effective });
     }
   }
   return presets;
@@ -67,13 +78,13 @@ export function checkPresetPackage(id, { targetInput = "", home = "" } = {}) {
   };
 }
 
-function readPresetPackageFromPath(directory) {
+function readPresetPackageFromPath(directory, source = "local") {
   const manifestPath = path.join(directory, "preset.yaml");
   assertPresetDirectory(directory);
   assertPresetManifestFile(directory, manifestPath);
   const raw = fs.readFileSync(manifestPath, "utf8");
   const manifest = parseSimpleYaml(raw);
-  return normalizePresetManifest(manifest, { id: normalizePresetId(manifest.id || path.basename(directory)), manifestPath, raw, source: "local" });
+  return normalizePresetManifest(manifest, { id: normalizePresetId(manifest.id || path.basename(directory)), manifestPath, raw, source });
 }
 
 function assertPresetDirectory(directory) {
@@ -95,38 +106,43 @@ function assertPresetManifestFile(directory, manifestPath) {
 
 export function installPresetPackage(source, { force = false, scope = "user", targetInput = ".", home = "" } = {}) {
   if (!source) throw new Error("Missing preset source");
-  const sourcePath = resolveInstallSource(source);
-  const stagedPreset = readPresetPackageFromPath(sourcePath);
-  const stagedReport = validatePresetPackage(stagedPreset);
-  if (stagedReport.failures.length) throw new Error(`Invalid preset package ${stagedPreset.id}: ${stagedReport.failures.join("; ")}`);
-  const id = stagedPreset.id;
-  if (!id) throw new Error("Preset manifest missing id");
-  const destination = scope === "project" ? projectPresetDestination(id, targetInput) : userPresetDestination(id, { home });
-  if (fs.existsSync(destination)) {
-    if (!force) throw new Error(`Preset already installed: ${id}. Re-run with --force to overwrite.`);
-  }
-  fs.mkdirSync(path.dirname(destination), { recursive: true });
-  const tempDestination = path.join(path.dirname(destination), `.${id}.install-${Date.now()}-${crypto.randomBytes(4).toString("hex")}`);
-  fs.rmSync(tempDestination, { recursive: true, force: true });
-  copyDirectory(sourcePath, tempDestination);
+  const resolvedSource = resolveInstallSource(source);
   try {
-    const tempPreset = readPresetPackageFromPath(tempDestination);
-    const tempReport = validatePresetPackage(tempPreset);
-    if (tempReport.failures.length) throw new Error(`Invalid preset package ${id}: ${tempReport.failures.join("; ")}`);
-    fs.rmSync(destination, { recursive: true, force: true });
-    fs.renameSync(tempDestination, destination);
-    const preset = readPresetPackage(id, scope === "project" ? { targetInput, home } : { home });
-    return {
-      installed: true,
-      id: preset.id,
-      version: preset.version,
-      source: preset.source,
-      destination: toPosix(destination),
-      manifestPath: preset.manifestRelativePath,
-    };
-  } catch (error) {
+    const sourcePath = resolvedSource.path;
+    const stagedPreset = readPresetPackageFromPath(sourcePath);
+    const stagedReport = validatePresetPackage(stagedPreset);
+    if (stagedReport.failures.length) throw new Error(`Invalid preset package ${stagedPreset.id}: ${stagedReport.failures.join("; ")}`);
+    const id = stagedPreset.id;
+    if (!id) throw new Error("Preset manifest missing id");
+    const destination = scope === "project" ? projectPresetDestination(id, targetInput) : userPresetDestination(id, { home });
+    if (fs.existsSync(destination)) {
+      if (!force) throw new Error(`Preset already installed: ${id}. Re-run with --force to overwrite.`);
+    }
+    fs.mkdirSync(path.dirname(destination), { recursive: true });
+    const tempDestination = path.join(path.dirname(destination), `.${id}.install-${Date.now()}-${crypto.randomBytes(4).toString("hex")}`);
     fs.rmSync(tempDestination, { recursive: true, force: true });
-    throw error;
+    copyDirectory(sourcePath, tempDestination);
+    try {
+      const tempPreset = readPresetPackageFromPath(tempDestination);
+      const tempReport = validatePresetPackage(tempPreset);
+      if (tempReport.failures.length) throw new Error(`Invalid preset package ${id}: ${tempReport.failures.join("; ")}`);
+      fs.rmSync(destination, { recursive: true, force: true });
+      fs.renameSync(tempDestination, destination);
+      const preset = readPresetPackage(id, scope === "project" ? { targetInput, home } : { home });
+      return {
+        installed: true,
+        id: preset.id,
+        version: preset.version,
+        source: preset.source,
+        destination: toPosix(destination),
+        manifestPath: preset.manifestRelativePath,
+      };
+    } catch (error) {
+      fs.rmSync(tempDestination, { recursive: true, force: true });
+      throw error;
+    }
+  } finally {
+    resolvedSource.cleanup();
   }
 }
 
@@ -226,7 +242,11 @@ export function validatePresetPackage(preset) {
       else validatePresetPackageFile(preset, entrypoint.command, `${name} command`, failures);
     }
   }
-  for (const templatePath of Object.values(preset.newTaskTemplates)) {
+  for (const [templateKey, templatePath] of Object.entries(preset.newTaskTemplates)) {
+    if (!allowedNewTaskTemplateKeys.has(templateKey)) {
+      failures.push(`unsupported newTask template: ${templateKey}`);
+      continue;
+    }
     const absolute = path.join(preset.directory, templatePath);
     if (!isInside(preset.directory, absolute)) failures.push(`template escapes preset package: ${templatePath}`);
     else validatePresetPackageFile(preset, templatePath, "template", failures);
@@ -593,12 +613,141 @@ function presetSearchRoots({ targetInput = "", home = "" } = {}) {
 
 function resolveInstallSource(source) {
   const localPath = path.resolve(source);
-  if (fs.existsSync(path.join(localPath, "preset.yaml"))) return localPath;
+  if (fs.existsSync(path.join(localPath, "preset.yaml"))) return { path: localPath, cleanup: () => {} };
+  if (fs.existsSync(localPath) && fs.statSync(localPath).isFile()) {
+    if (!localPath.toLowerCase().endsWith(".zip")) throw new Error(`Preset source file must be a .zip archive: ${toPosix(localPath)}`);
+    return resolveZipInstallSource(localPath);
+  }
   const builtinPath = path.join(builtinPresetRoot, normalizePresetId(source));
-  if (fs.existsSync(path.join(builtinPath, "preset.yaml"))) return builtinPath;
+  if (fs.existsSync(path.join(builtinPath, "preset.yaml"))) return { path: builtinPath, cleanup: () => {} };
   throw new Error(`Preset source not found: ${source}`);
 }
 
+function resolveZipInstallSource(sourcePath) {
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "harness-preset-archive-"));
+  try {
+    extractPresetZip(sourcePath, tempRoot);
+    return {
+      path: presetRootFromExtractedArchive(tempRoot),
+      cleanup: () => fs.rmSync(tempRoot, { recursive: true, force: true }),
+    };
+  } catch (error) {
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+function presetRootFromExtractedArchive(tempRoot) {
+  if (fs.existsSync(path.join(tempRoot, "preset.yaml"))) return tempRoot;
+  const children = fs.readdirSync(tempRoot, { withFileTypes: true })
+    .filter((entry) => entry.name !== "__MACOSX" && entry.name !== ".DS_Store");
+  const presetDirs = children
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => path.join(tempRoot, entry.name))
+    .filter((directory) => fs.existsSync(path.join(directory, "preset.yaml")));
+  if (presetDirs.length === 1) return presetDirs[0];
+  throw new Error("Preset archive must contain preset.yaml at the archive root or inside one top-level directory.");
+}
+
+function extractPresetZip(sourcePath, destinationRoot) {
+  const archiveStat = fs.statSync(sourcePath);
+  if (archiveStat.size > maxPresetArchiveBytes) throw new Error("Preset archive file is too large.");
+  const archive = fs.readFileSync(sourcePath);
+  const eocdOffset = findZipEndOfCentralDirectory(archive);
+  const entryCount = archive.readUInt16LE(eocdOffset + 10);
+  const centralSize = archive.readUInt32LE(eocdOffset + 12);
+  const centralOffset = archive.readUInt32LE(eocdOffset + 16);
+  if (entryCount === 0xffff || centralSize === 0xffffffff || centralOffset === 0xffffffff) {
+    throw new Error("Zip64 preset archives are not supported.");
+  }
+  if (entryCount > maxPresetArchiveEntries) throw new Error(`Preset archive has too many entries: ${entryCount}`);
+  if (centralOffset + centralSize > archive.length) throw new Error("Invalid preset archive central directory.");
+  const written = new Set();
+  let cursor = centralOffset;
+  let totalUncompressed = 0;
+  for (let index = 0; index < entryCount; index += 1) {
+    if (archive.readUInt32LE(cursor) !== 0x02014b50) throw new Error("Invalid preset archive central directory entry.");
+    const flags = archive.readUInt16LE(cursor + 8);
+    const method = archive.readUInt16LE(cursor + 10);
+    const compressedSize = archive.readUInt32LE(cursor + 20);
+    const uncompressedSize = archive.readUInt32LE(cursor + 24);
+    const nameLength = archive.readUInt16LE(cursor + 28);
+    const extraLength = archive.readUInt16LE(cursor + 30);
+    const commentLength = archive.readUInt16LE(cursor + 32);
+    const externalAttributes = archive.readUInt32LE(cursor + 38);
+    const localOffset = archive.readUInt32LE(cursor + 42);
+    const rawName = archive.slice(cursor + 46, cursor + 46 + nameLength).toString(flags & 0x0800 ? "utf8" : "utf8");
+    cursor += 46 + nameLength + extraLength + commentLength;
+    if (shouldSkipZipEntry(rawName)) continue;
+    if (flags & 0x0001) throw new Error(`Encrypted preset archive entries are not supported: ${rawName}`);
+    if (method !== 0 && method !== 8) throw new Error(`Unsupported preset archive compression method ${method}: ${rawName}`);
+    const mode = (externalAttributes >>> 16) & 0o170000;
+    if (mode === 0o120000) throw new Error(`Preset archive must not contain symlinks: ${rawName}`);
+    const entryName = safeZipEntryName(rawName);
+    if (!entryName) continue;
+    if (entryName.endsWith("/")) {
+      fs.mkdirSync(path.join(destinationRoot, entryName), { recursive: true });
+      continue;
+    }
+    if (written.has(entryName)) throw new Error(`Preset archive contains duplicate entry: ${entryName}`);
+    if (uncompressedSize > maxPresetArchiveUncompressedBytes - totalUncompressed) throw new Error("Preset archive is too large.");
+    const data = readZipEntryData(archive, { localOffset, compressedSize, uncompressedSize, method, name: entryName });
+    totalUncompressed += data.length;
+    const destination = path.resolve(destinationRoot, entryName);
+    if (!isInside(path.resolve(destinationRoot), destination)) throw new Error(`Preset archive entry escapes extraction root: ${rawName}`);
+    fs.mkdirSync(path.dirname(destination), { recursive: true });
+    fs.writeFileSync(destination, data);
+    written.add(entryName);
+  }
+}
+
+function findZipEndOfCentralDirectory(archive) {
+  const minOffset = Math.max(0, archive.length - 22 - 65535);
+  for (let offset = archive.length - 22; offset >= minOffset; offset -= 1) {
+    if (archive.readUInt32LE(offset) === 0x06054b50) return offset;
+  }
+  throw new Error("Invalid preset zip archive: end of central directory not found.");
+}
+
+function readZipEntryData(archive, { localOffset, compressedSize, uncompressedSize, method, name }) {
+  if (localOffset + 30 > archive.length || archive.readUInt32LE(localOffset) !== 0x04034b50) {
+    throw new Error(`Invalid preset archive local header: ${name}`);
+  }
+  const localNameLength = archive.readUInt16LE(localOffset + 26);
+  const localExtraLength = archive.readUInt16LE(localOffset + 28);
+  const dataStart = localOffset + 30 + localNameLength + localExtraLength;
+  const dataEnd = dataStart + compressedSize;
+  if (dataEnd > archive.length) throw new Error(`Invalid preset archive entry size: ${name}`);
+  const compressed = archive.slice(dataStart, dataEnd);
+  let data;
+  try {
+    data = method === 0 ? Buffer.from(compressed) : zlib.inflateRawSync(compressed, { maxOutputLength: uncompressedSize });
+  } catch (error) {
+    throw new Error(`Preset archive entry could not be decompressed within its declared size: ${name}`);
+  }
+  if (data.length !== uncompressedSize) throw new Error(`Preset archive entry size mismatch: ${name}`);
+  return data;
+}
+
+function shouldSkipZipEntry(rawName) {
+  const normalized = String(rawName || "").replace(/\\/g, "/");
+  return normalized === "__MACOSX/" || normalized.startsWith("__MACOSX/") || normalized.endsWith("/.DS_Store") || normalized === ".DS_Store";
+}
+
+function safeZipEntryName(rawName) {
+  if (String(rawName).includes("\0")) throw new Error("Preset archive entry contains NUL byte.");
+  const withSlashes = String(rawName || "").replace(/\\/g, "/");
+  if (/^[A-Za-z]:/.test(withSlashes) || withSlashes.startsWith("/")) {
+    throw new Error(`Preset archive entry must be relative: ${rawName}`);
+  }
+  const normalized = path.posix.normalize(withSlashes);
+  if (normalized === "." || normalized === "") return "";
+  if (normalized === ".." || normalized.startsWith("../") || normalized.includes("/../")) {
+    throw new Error(`Preset archive entry escapes extraction root: ${rawName}`);
+  }
+  return withSlashes.endsWith("/") ? `${normalized}/` : normalized;
+}
+
 function copyDirectory(source, destination) {
   fs.mkdirSync(destination, { recursive: true });
   for (const entry of fs.readdirSync(source, { withFileTypes: true })) {

package/scripts/lib/review-confirm-git-gate.mjs

@@ -141,7 +141,7 @@ function assertAllowedPaths(paths) {
     throw new ReviewConfirmGitGateError("Review confirmation write allowlist contains forbidden paths.", {
       code: "git-allowlist-forbidden-path",
       details: { disallowed },
-      recovery: ["Limit review-confirm writes to the current task review.md and progress.md files."],
+      recovery: ["Limit review-confirm writes to the current task INDEX.md file."],
     });
   }
 }

package/scripts/lib/status-builder.mjs

@@ -0,0 +1,88 @@
+import path from "node:path";
+import { normalizeTarget, toPosix } from "./core-shared.mjs";
+import { capabilityDefinitions, readCapabilityRegistry } from "./capability-registry.mjs";
+import { summarizeGitState } from "./git-status-summary.mjs";
+import { collectTasks, taskCutoverCounters } from "./task-scanner.mjs";
+
+export function buildStatusData(targetInput, options = {}) {
+  const target = targetInput?.projectRoot ? targetInput : normalizeTarget(targetInput);
+  const validationMode = options.validationMode || "data-only";
+  const gitState = options.gitState || summarizeGitState(target);
+  const registry = options.capabilityState?.registry || readCapabilityRegistry(target);
+  const detected = options.capabilityState?.detected || [];
+  const capabilityWarnings = options.capabilityState?.warnings || [];
+  const failures = [...(options.failures || [])];
+  const warnings = [...(options.warnings || [])];
+  const legacy = options.legacy || { status: "skipped", code: 0, stdout: "", stderr: "" };
+  const tasks = options.tasks || collectTasks(target, {
+    requireGeneratedScaffoldProvenance: options.requireGeneratedScaffoldProvenance === true,
+    taskPlanPaths: options.taskPlanPaths,
+    closeoutContent: options.closeoutContent,
+  });
+  const briefReady = tasks.filter((task) => task.briefSource === "standalone").length;
+  const briefMissing = tasks.length - briefReady;
+  const capabilityNames = new Map(registry.capabilities.map((capability) => [capability.name, capability]));
+  for (const capability of detected) {
+    if (!capabilityNames.has(capability)) capabilityNames.set(capability, { name: capability, state: "configured" });
+  }
+  const cutoverCounters = taskCutoverCounters(tasks);
+  const fullCutoverEligible =
+    validationMode === "validated" &&
+    failures.length === 0 &&
+    warnings.length === 0 &&
+    cutoverCounters.legacyVisualOnlyCount === 0 &&
+    cutoverCounters.unknownClassificationCount === 0 &&
+    cutoverCounters.weakBriefCount === 0 &&
+    cutoverCounters.missingCanonicalVisualMapCount === 0;
+
+  return {
+    project: {
+      name: path.basename(target.projectRoot),
+      root: `TARGET:${target.docsOnly ? toPosix(path.relative(target.projectRoot, target.docsRoot)) : "."}`,
+      docsOnly: target.docsOnly,
+    },
+    schemaVersion: 2,
+    generatedAt: options.generatedAt || new Date().toISOString(),
+    mode: registry.mode,
+    checkState: {
+      status: failures.length > 0 ? "fail" : warnings.length > 0 ? "warn" : "pass",
+      validationMode,
+      failures: failures.length,
+      warnings: warnings.length,
+      details: { failures, warnings },
+      legacy,
+    },
+    git: gitState.summary,
+    summary: {
+      tasks: tasks.length,
+      briefCoverage: {
+        ready: briefReady,
+        missing: briefMissing,
+        total: tasks.length,
+      },
+      visualMapCoverage: {
+        canonical: tasks.filter((task) => task.visualMapSource === "canonical").length,
+        legacyOnly: cutoverCounters.legacyVisualOnlyCount,
+        missing: tasks.filter((task) => task.visualMapStatus === "missing").length,
+        total: tasks.length,
+      },
+      fullCutoverEligible,
+      legacyVisualOnlyCount: cutoverCounters.legacyVisualOnlyCount,
+      unknownClassificationCount: cutoverCounters.unknownClassificationCount,
+      weakBriefCount: cutoverCounters.weakBriefCount,
+      visualMapRequiredCount: cutoverCounters.visualMapRequiredCount,
+      missingCanonicalVisualMapCount: cutoverCounters.missingCanonicalVisualMapCount,
+    },
+    capabilities: [...capabilityNames.values()].map((capability) => ({
+      name: capability.name,
+      state: capability.state || "configured",
+      dependencyStatus: capabilityDefinitions[capability.name]?.dependencies.every((dependency) => capabilityNames.has(dependency))
+        ? "valid"
+        : "invalid",
+      warnings: capabilityWarnings.filter((warning) => warning.includes(capability.name)),
+    })),
+    tasks,
+    handoffs: tasks.flatMap((task) => task.handoffs || []),
+    recentActivity: tasks.slice(0, 8).map((task) => ({ at: new Date().toISOString(), type: "task", summary: task.title })),
+  };
+}

package/scripts/lib/status-dashboard-renderer.mjs

@@ -1,13 +1,16 @@
+import { implementationPhases } from "./phase-kind.mjs";
+
 export function renderDashboard(status) {
   const taskCards = status.tasks
     .map((task) => {
       const phases = task.phases
         .map(
-          (phase) => `<div class="phase ${escapeHtml(phase.state)}">
-            <div class="phase-top"><strong>${escapeHtml(phase.id)}</strong><span>${phase.completion}%</span></div>
+          (phase) => `<div class="phase ${escapeHtml(phase.state)} ${escapeHtml(phase.kind || "execution")}">
+            <div class="phase-top"><strong>${escapeHtml(phase.id)}</strong><span>${escapeHtml(phase.kind || "execution")} · ${phase.completion}%</span></div>
             <div class="phase-output">${escapeHtml(phase.output)}</div>
             <div class="meter"><i style="width:${phase.completion}%"></i></div>
-            <div class="muted">${escapeHtml(phase.state)} · evidence ${escapeHtml(phase.evidenceStatus)}</div>
+            <div class="muted">${escapeHtml(phase.state)} · actor ${escapeHtml(phase.actor || "agent")} · evidence ${escapeHtml(phase.evidenceStatus)}</div>
+            ${phase.exitCommand ? `<div class="muted">exit ${escapeHtml(phase.exitCommand)}</div>` : ""}
           </div>`,
         )
         .join("");
@@ -91,7 +94,7 @@ function escapeHtml(value) {
 }
 
 function evidenceCompletion(phases) {
-  const scored = phases.filter((phase) => phase.state !== "skipped");
+  const scored = implementationPhases(phases);
   if (scored.length === 0) return 0;
   const score = scored.reduce((sum, phase) => {
     if (["present", "waived"].includes(phase.evidenceStatus)) return sum + 100;