harnery 0.32.0 → 0.34.0

package/src/core/config.ts

@@ -9,8 +9,8 @@
  * Fields owned here: `binName` (host CLI name for agent-facing strings),
  * `hooksSetupHint`, `agents`, `tools`, `workflow`, `skills`, `presence`, plus the tunable
  * `coord` (heartbeat freshness), `artifacts` (working-file retention),
- * `backup` (restic repo/password/prune policy), and `sync` (rclone
- * remote/prefix) sections. The `files` deny/override section
+ * `backup` (restic repo/password/prune policy), `sync` (rclone
+ * remote/prefix), and `web` (dashboard port) sections. The `files` deny/override section
  * is parsed separately by `web/lib/files.ts`.
  *
  * Env vars and CLI flags override any config value per invocation (each accessor
@@ -30,6 +30,25 @@ export const DEFAULT_BIN_NAME = "harn";
 /** Heartbeat-freshness default (seconds): the sweep window when nothing overrides it. */
 export const DEFAULT_FRESHNESS_SECS = 600;
 
+/** Mnemonic dashboard port: 4276 spells HARN on a phone keypad. */
+export const DEFAULT_WEB_PORT = 4276;
+
+export interface SessionFinalizationConfig {
+  archiveGraceSeconds: number;
+  idleObserveSeconds: number;
+  idleFinalizeSeconds: number;
+  cascadeGraceSeconds: number;
+  reconcileIntervalSeconds: number;
+}
+
+export const DEFAULT_SESSION_FINALIZATION_CONFIG: SessionFinalizationConfig = {
+  archiveGraceSeconds: 600,
+  idleObserveSeconds: 3 * 24 * 60 * 60,
+  idleFinalizeSeconds: 7 * 24 * 60 * 60,
+  cascadeGraceSeconds: 60 * 60,
+  reconcileIntervalSeconds: 15 * 60,
+};
+
 export type AgentFinalizationDisposition = "git" | "output";
 
 export interface AgentFinalizationRoot {
@@ -88,7 +107,17 @@ interface HarneryConfig {
    * Coord-layer tunables. `freshness_seconds` is the heartbeat age above which
    * the sweeper prunes an agent (default 600). Read via `coordFreshnessSeconds()`.
    */
-  coord?: { freshness_seconds?: number };
+  coord?: {
+    freshness_seconds?: number;
+    run_quality?: unknown;
+    finalization?: {
+      archive_grace_seconds?: number;
+      idle_observe_seconds?: number;
+      idle_finalize_seconds?: number;
+      cascade_grace_seconds?: number;
+      reconcile_interval_seconds?: number;
+    };
+  };
   /**
    * Managed working-artifact defaults. `default_retention_days` is the
    * create-time TTL when the caller does not pass `artifacts create --days`.
@@ -111,6 +140,8 @@ interface HarneryConfig {
    * `~/.config/harnery/sync.json`, which is consulted as a lower-precedence fallback.
    */
   sync?: { remote?: string; prefix?: string };
+  /** Standalone dashboard defaults. */
+  web?: { port?: number; bind?: string };
   [k: string]: unknown;
 }
 
@@ -194,6 +225,61 @@ function parseConfigFile(p: string): HarneryConfig {
   return {};
 }
 
+export interface CoordRunQualityConfigSource {
+  value: unknown;
+  invalid: boolean;
+  /** Stable digest seed that contains no config values when parsing failed. */
+  digest_seed: unknown;
+}
+
+/**
+ * Effective user-plus-project `coord.run_quality` value with parse diagnostics.
+ * The ordinary config reader stays fail-soft; this one lets the guard visibly
+ * disable itself rather than silently substituting defaults for malformed JSONC.
+ */
+export function coordRunQualityConfigSource(root: string): CoordRunQualityConfigSource {
+  const projectPath = join(root, ".harnery", "config.jsonc");
+  const userPath = userConfigPath();
+  const layers = [userPath, projectPath].map((path) => parseConfigLayer(path));
+  const invalid = layers.filter((layer) => layer.invalid);
+  if (invalid.length > 0) {
+    return {
+      value: undefined,
+      invalid: true,
+      digest_seed: invalid.map((layer) => ({
+        path_kind: layer.path_kind,
+        signature: layer.signature,
+      })),
+    };
+  }
+  const merged = mergeConfig(layers[0]!.config, layers[1]!.config);
+  return {
+    value: merged.coord?.run_quality,
+    invalid: false,
+    digest_seed: merged.coord?.run_quality,
+  };
+}
+
+function parseConfigLayer(path: string): {
+  config: HarneryConfig;
+  invalid: boolean;
+  path_kind: "user" | "project";
+  signature: string | null;
+} {
+  const pathKind = path === userConfigPath() ? "user" : "project";
+  const signature = statSignature(path);
+  if (signature === null) return { config: {}, invalid: false, path_kind: pathKind, signature };
+  try {
+    const value = JSON.parse(stripJsonComments(readFileSync(path, "utf8"))) as unknown;
+    if (isPlainObject(value)) {
+      return { config: value as HarneryConfig, invalid: false, path_kind: pathKind, signature };
+    }
+  } catch {
+    // The guard reports one bounded health event for this file signature.
+  }
+  return { config: {}, invalid: true, path_kind: pathKind, signature };
+}
+
 function isPlainObject(v: unknown): v is Record<string, unknown> {
   return typeof v === "object" && v !== null && !Array.isArray(v);
 }
@@ -445,6 +531,65 @@ export function coordFreshnessSeconds(coordRoot?: string | null): number {
   return DEFAULT_FRESHNESS_SECS;
 }
 
+function parseWebPort(value: unknown, source: string): number {
+  const port = typeof value === "number" ? value : Number(value);
+  if (!Number.isInteger(port) || port < 1024 || port > 65535) {
+    throw new RangeError(`${source} must be an integer from 1024 through 65535`);
+  }
+  return port;
+}
+
+/**
+ * Resolve the standalone dashboard port.
+ *
+ * Precedence: explicit `--port` flag, `HARNERY_WEB_PORT`, merged
+ * `.harnery/config.jsonc` `web.port`, then the mnemonic built-in default 4276.
+ */
+export function resolveWebPort(explicitPort?: string, coordRoot?: string | null): number {
+  if (explicitPort !== undefined && explicitPort.trim() !== "") {
+    return parseWebPort(explicitPort, "--port");
+  }
+  const envPort = coordEnv("WEB_PORT");
+  if (envPort !== undefined && envPort.trim() !== "") {
+    return parseWebPort(envPort, "HARNERY_WEB_PORT");
+  }
+  const root = coordRoot ?? findCoordRoot();
+  const configuredPort = root ? readConfig(root).web?.port : undefined;
+  if (configuredPort !== undefined) {
+    return parseWebPort(configuredPort, "web.port");
+  }
+  return DEFAULT_WEB_PORT;
+}
+
+/** Policy for converging independent termination signals on one finalizer. */
+export function sessionFinalizationConfig(coordRoot?: string | null): SessionFinalizationConfig {
+  const root = coordRoot ?? findCoordRoot();
+  const configured = root ? readConfig(root).coord?.finalization : undefined;
+  const defaults = DEFAULT_SESSION_FINALIZATION_CONFIG;
+  const archiveGraceSeconds = posIntOr(
+    configured?.archive_grace_seconds,
+    defaults.archiveGraceSeconds,
+  );
+  const idleObserveSeconds = posIntOr(
+    configured?.idle_observe_seconds,
+    defaults.idleObserveSeconds,
+  );
+  const idleFinalizeSeconds = Math.max(
+    idleObserveSeconds,
+    posIntOr(configured?.idle_finalize_seconds, defaults.idleFinalizeSeconds),
+  );
+  return {
+    archiveGraceSeconds,
+    idleObserveSeconds,
+    idleFinalizeSeconds,
+    cascadeGraceSeconds: posIntOr(configured?.cascade_grace_seconds, defaults.cascadeGraceSeconds),
+    reconcileIntervalSeconds: posIntOr(
+      configured?.reconcile_interval_seconds,
+      defaults.reconcileIntervalSeconds,
+    ),
+  };
+}
+
 /**
  * Default retention for a newly-created working artifact. Precedence:
  * `HARNERY_ARTIFACT_RETENTION_DAYS` -> project/user config

package/src/core/context/index.ts

@@ -9,7 +9,8 @@ import { spawnSync } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import type { Adapter } from "../hooks/events/schema.ts";
+import type { Adapter } from "../adapter.ts";
+import { readLiveCoordinationRow } from "../agents/state/live-coordination-view.ts";
 
 export const CONTEXT_SCHEMA_VERSION = 1 as const;
 export const MAX_CAPSULE_BYTES = 32 * 1024;
@@ -71,12 +72,9 @@ export interface ContinuityCapsule {
   context?: ContextSample;
   work: {
     task?: string;
-    turn_summary?: string;
     continuation_note?: string;
     files_held: string[];
     files_held_truncated?: boolean;
-    last_tool?: string;
-    last_tool_target?: string;
   };
   repo: RepoSnapshot;
 }
@@ -123,10 +121,7 @@ export interface PreparedContextRecovery {
 interface HeartbeatSnapshot {
   model?: string;
   task?: string;
-  turn_summary?: string;
   files_touched?: string[];
-  last_tool?: string;
-  last_tool_target?: string;
 }
 
 /** Parse the context-window shapes exposed by current adapter hook/status data. */
@@ -379,18 +374,12 @@ export function renderRecoveryBriefing(capsule: ContinuityCapsule, liveRepo: Rep
     `[harnery context continuity] Recovered generation ${capsule.generation} after native context compaction.`,
   ];
   if (capsule.work.task) lines.push(`Task: ${capsule.work.task}`);
-  if (capsule.work.turn_summary) lines.push(`Last progress: ${capsule.work.turn_summary}`);
   if (capsule.work.continuation_note) {
     lines.push(`Continuation note: ${capsule.work.continuation_note}`);
   }
   if (capsule.work.files_held.length > 0) {
     lines.push(`Files held: ${capsule.work.files_held.join(", ")}`);
   }
-  if (capsule.work.last_tool) {
-    lines.push(
-      `Last tool: ${capsule.work.last_tool}${capsule.work.last_tool_target ? ` (${capsule.work.last_tool_target})` : ""}`,
-    );
-  }
 
   const drift: string[] = [];
   if (capsule.repo.branch && liveRepo.branch && capsule.repo.branch !== liveRepo.branch) {
@@ -446,17 +435,20 @@ function buildWorkSnapshot(
     : [];
   return {
     task: clampString(heartbeat?.task, 1_000),
-    turn_summary: clampString(heartbeat?.turn_summary, 3_000),
     continuation_note: clampString(continuationNote, 3_000),
     files_held: files.slice(0, MAX_SNAPSHOT_PATHS),
     ...(files.length > MAX_SNAPSHOT_PATHS ? { files_held_truncated: true } : {}),
-    last_tool: clampString(heartbeat?.last_tool, 200),
-    last_tool_target: clampString(heartbeat?.last_tool_target, 1_000),
   };
 }
 
 function readHeartbeat(coordRoot: string, instanceId: string): HeartbeatSnapshot | null {
-  return readJson<HeartbeatSnapshot>(join(coordRoot, ".harnery", "active", `${instanceId}.json`));
+  const row = readLiveCoordinationRow(coordRoot, instanceId);
+  if (!row) return null;
+  return {
+    model: row.model,
+    task: row.task,
+    files_touched: row.files_touched,
+  };
 }
 
 function newState(input: {

package/src/core/events/span-parent.ts

@@ -0,0 +1,46 @@
+export interface OpenToolSpanForCommandParent {
+  span_id: `span_${string}`;
+  turn_id?: `tid_${string}`;
+  requested_event_id?: `evt_${string}`;
+  tool_name?: string;
+}
+
+const SHELL_TOOL_NAMES = new Set([
+  "apply_patch",
+  "bash",
+  "exec",
+  "exec_command",
+  "execute",
+  "powershell",
+  "run_command",
+  "shell",
+  "terminal",
+]);
+
+/**
+ * Choose a command's tool parent only when attribution cannot silently pick
+ * the wrong span. A single open tool is unambiguous. With parallel tools,
+ * exactly one shell-class span may be selected; every other case stays
+ * top-level so any over-count remains visible.
+ */
+export function selectCommandParentSpan(
+  spans: readonly OpenToolSpanForCommandParent[],
+  turnId: `tid_${string}`,
+): `span_${string}` | undefined {
+  const open = spans.filter(
+    (span) => span.turn_id === turnId && span.requested_event_id !== undefined,
+  );
+  if (open.length === 1) return open[0]?.span_id;
+  const shell = open.filter((span) => isShellToolName(span.tool_name));
+  return shell.length === 1 ? shell[0]?.span_id : undefined;
+}
+
+export function isShellToolName(name: string | undefined): boolean {
+  if (!name) return false;
+  const normalized = name
+    .trim()
+    .toLowerCase()
+    .replace(/^.*[.:/]/, "")
+    .replaceAll("-", "_");
+  return SHELL_TOOL_NAMES.has(normalized);
+}

package/src/core/events/v3/advance.ts

@@ -0,0 +1,168 @@
+import type { TSchema } from "@sinclair/typebox";
+import { canonicalJsonV3 } from "./canonical.ts";
+
+export interface SchemaAdvanceEligibilityV3 {
+  eligible: boolean;
+  strict: boolean;
+  issues: string[];
+}
+
+/**
+ * Mechanical half of ADR 0080's in-place advance gate. It proves that every
+ * value accepted by the prior JSON Schema remains accepted by the next schema.
+ * Semantic reinterpretations remain breaking even when this structural check
+ * passes and require genesis review.
+ */
+export function validateAdditiveSchemaAdvanceV3(
+  prior: TSchema,
+  next: TSchema,
+): SchemaAdvanceEligibilityV3 {
+  const issues: string[] = [];
+  const result = isSuperset(prior as JsonSchema, next as JsonSchema, "$", issues);
+  return {
+    eligible: result.compatible && result.strict,
+    strict: result.strict,
+    issues: [...new Set(issues)].sort(),
+  };
+}
+
+type JsonSchema = Record<string, unknown>;
+type Compatibility = { compatible: boolean; strict: boolean };
+
+function isSuperset(
+  prior: JsonSchema,
+  next: JsonSchema,
+  path: string,
+  issues: string[],
+): Compatibility {
+  const priorAnyOf = schemaArray(prior.anyOf);
+  const nextAnyOf = schemaArray(next.anyOf);
+  if (priorAnyOf || nextAnyOf) {
+    if (!priorAnyOf || !nextAnyOf) return incompatible(path, "union_shape_changed", issues);
+    const used = new Set<number>();
+    let strict = nextAnyOf.length > priorAnyOf.length;
+    for (const [priorIndex, priorBranch] of priorAnyOf.entries()) {
+      let match: { index: number; result: Compatibility } | undefined;
+      for (const [nextIndex, nextBranch] of nextAnyOf.entries()) {
+        if (used.has(nextIndex)) continue;
+        const branchIssues: string[] = [];
+        const result = isSuperset(
+          priorBranch,
+          nextBranch,
+          `${path}/anyOf/${priorIndex}`,
+          branchIssues,
+        );
+        if (result.compatible) {
+          match = { index: nextIndex, result };
+          break;
+        }
+      }
+      if (!match)
+        return incompatible(`${path}/anyOf/${priorIndex}`, "branch_removed_or_narrowed", issues);
+      used.add(match.index);
+      strict ||= match.result.strict;
+    }
+    return { compatible: true, strict };
+  }
+
+  if (prior.type === "object" || next.type === "object") {
+    if (prior.type !== "object" || next.type !== "object") {
+      return incompatible(path, "type_changed", issues);
+    }
+    if (prior.additionalProperties !== next.additionalProperties) {
+      return incompatible(path, "additional_properties_changed", issues);
+    }
+    const priorProperties = schemaMap(prior.properties);
+    const nextProperties = schemaMap(next.properties);
+    const priorRequired = stringSet(prior.required);
+    const nextRequired = stringSet(next.required);
+    let strict = false;
+    for (const name of priorRequired) {
+      if (!nextRequired.has(name)) strict = true;
+    }
+    for (const name of nextRequired) {
+      if (!priorRequired.has(name)) {
+        return incompatible(`${path}/properties/${name}`, "optional_became_required", issues);
+      }
+    }
+    for (const [name, priorProperty] of Object.entries(priorProperties)) {
+      const nextProperty = nextProperties[name];
+      if (!nextProperty)
+        return incompatible(`${path}/properties/${name}`, "property_removed", issues);
+      const result = isSuperset(priorProperty, nextProperty, `${path}/properties/${name}`, issues);
+      if (!result.compatible) return result;
+      strict ||= result.strict;
+    }
+    for (const name of Object.keys(nextProperties)) {
+      if (!(name in priorProperties)) {
+        if (nextRequired.has(name)) {
+          return incompatible(`${path}/properties/${name}`, "new_property_is_required", issues);
+        }
+        strict = true;
+      }
+    }
+    return { compatible: true, strict };
+  }
+
+  if (prior.type === "array" || next.type === "array") {
+    if (prior.type !== "array" || next.type !== "array")
+      return incompatible(path, "type_changed", issues);
+    if (number(next.minItems, 0) < number(prior.minItems, 0)) {
+      // A lower minimum broadens acceptance.
+    } else if (number(next.minItems, 0) > number(prior.minItems, 0)) {
+      return incompatible(path, "array_minimum_narrowed", issues);
+    }
+    const priorMax = number(prior.maxItems, Number.POSITIVE_INFINITY);
+    const nextMax = number(next.maxItems, Number.POSITIVE_INFINITY);
+    if (nextMax < priorMax) return incompatible(path, "array_maximum_narrowed", issues);
+    const priorItems = prior.items as JsonSchema | undefined;
+    const nextItems = next.items as JsonSchema | undefined;
+    if (!!priorItems !== !!nextItems) return incompatible(path, "array_items_changed", issues);
+    const itemResult =
+      priorItems && nextItems
+        ? isSuperset(priorItems, nextItems, `${path}/items`, issues)
+        : { compatible: true, strict: false };
+    return {
+      compatible: itemResult.compatible,
+      strict:
+        itemResult.strict ||
+        number(next.minItems, 0) < number(prior.minItems, 0) ||
+        nextMax > priorMax,
+    };
+  }
+
+  const ignored = new Set(["$id", "title", "description"]);
+  const priorComparable = Object.fromEntries(
+    Object.entries(prior).filter(([key]) => !ignored.has(key)),
+  );
+  const nextComparable = Object.fromEntries(
+    Object.entries(next).filter(([key]) => !ignored.has(key)),
+  );
+  if (canonicalJsonV3(priorComparable) !== canonicalJsonV3(nextComparable)) {
+    return incompatible(path, "constraint_changed", issues);
+  }
+  return { compatible: true, strict: false };
+}
+
+function incompatible(path: string, reason: string, issues: string[]): Compatibility {
+  issues.push(`${path}:${reason}`);
+  return { compatible: false, strict: false };
+}
+
+function schemaArray(value: unknown): JsonSchema[] | undefined {
+  return Array.isArray(value) ? (value as JsonSchema[]) : undefined;
+}
+
+function schemaMap(value: unknown): Record<string, JsonSchema> {
+  return value && typeof value === "object" ? (value as Record<string, JsonSchema>) : {};
+}
+
+function stringSet(value: unknown): Set<string> {
+  return new Set(
+    Array.isArray(value) ? value.filter((item): item is string => typeof item === "string") : [],
+  );
+}
+
+function number(value: unknown, fallback: number): number {
+  return typeof value === "number" ? value : fallback;
+}