harnery 0.30.0 → 0.31.1

package/src/core/context/index.ts

@@ -1,7 +1,7 @@
 /**
- * Context continuity: durable, structured state around native harness
- * compaction. Harnery does not decide when a harness compacts. It records
- * context telemetry when the harness exposes it, checkpoints external work
+ * Context continuity: durable, structured state around native adapter
+ * compaction. Harnery does not decide when a adapter compacts. It records
+ * context telemetry when the adapter exposes it, checkpoints external work
  * state before compaction, and renders a verified recovery briefing after it.
  */
 
@@ -9,7 +9,7 @@ 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 { Harness } from "../hooks/events/schema.ts";
+import type { Adapter } from "../hooks/events/schema.ts";
 
 export const CONTEXT_SCHEMA_VERSION = 1 as const;
 export const MAX_CAPSULE_BYTES = 32 * 1024;
@@ -23,7 +23,7 @@ export type CheckpointReason = "manual" | "pressure" | "pre_compact" | "session_
 
 export interface ContextSample {
   session_id: string;
-  harness: Harness;
+  adapter: Adapter;
   model?: string;
   used_tokens?: number;
   window_tokens?: number;
@@ -65,7 +65,7 @@ export interface ContinuityCapsule {
   session: {
     session_id: string;
     instance_id: string;
-    harness: Harness;
+    adapter: Adapter;
     model?: string;
   };
   context?: ContextSample;
@@ -83,7 +83,7 @@ export interface ContinuityCapsule {
 
 export interface ExtractContextSampleOptions {
   sessionId: string;
-  harness: Harness;
+  adapter: Adapter;
   model?: string;
   source?: ContextSampleSource;
   confidence?: ContextSampleConfidence;
@@ -93,7 +93,7 @@ export interface ExtractContextSampleOptions {
 export interface CheckpointContextInput {
   sessionId: string;
   instanceId: string;
-  harness: Harness;
+  adapter: Adapter;
   cwd: string;
   reason: CheckpointReason;
   model?: string;
@@ -129,7 +129,7 @@ interface HeartbeatSnapshot {
   last_tool_target?: string;
 }
 
-/** Parse the context-window shapes exposed by current harness hook/status data. */
+/** Parse the context-window shapes exposed by current adapter hook/status data. */
 export function extractContextSample(
   payload: Record<string, unknown>,
   options: ExtractContextSampleOptions,
@@ -177,7 +177,7 @@ export function extractContextSample(
 
   return {
     session_id: options.sessionId,
-    harness: options.harness,
+    adapter: options.adapter,
     model,
     used_tokens: usedTokens,
     window_tokens: windowTokens,
@@ -245,7 +245,7 @@ export function checkpointContext(
     session: {
       session_id: input.sessionId,
       instance_id: input.instanceId,
-      harness: input.harness,
+      adapter: input.adapter,
       model: input.model ?? current.latest_context?.model ?? heartbeat?.model,
     },
     context: current.latest_context,
@@ -271,7 +271,7 @@ export function checkpointContext(
   return { capsule, path: absolutePath, state: next, reused: false };
 }
 
-/** Prepare a briefing without claiming that a harness has accepted it yet. */
+/** Prepare a briefing without claiming that a adapter has accepted it yet. */
 export function prepareContextRecovery(
   coordRoot: string,
   input: { sessionId: string; instanceId: string; cwd: string },
@@ -298,7 +298,7 @@ export function prepareContextRecovery(
   return { state: current, capsule, briefing };
 }
 
-/** Advance continuity only after the harness context channel accepted the briefing. */
+/** Advance continuity only after the adapter context channel accepted the briefing. */
 export function completeContextRecovery(
   coordRoot: string,
   input: { sessionId: string; instanceId: string },
@@ -319,7 +319,7 @@ export function completeContextRecovery(
   return recovered;
 }
 
-/** Record that the harness, rather than Harnery, reported compaction complete. */
+/** Record that the adapter, rather than Harnery, reported compaction complete. */
 export function markContextCompactionCompleted(
   coordRoot: string,
   input: { sessionId: string; instanceId: string; observedAt?: string },
@@ -532,7 +532,7 @@ function git(cwd: string, args: string[]): string | undefined {
 function sameMeasurement(a: ContextSample | undefined, b: ContextSample): boolean {
   if (!a) return false;
   return (
-    a.harness === b.harness &&
+    a.adapter === b.adapter &&
     a.model === b.model &&
     a.used_tokens === b.used_tokens &&
     a.window_tokens === b.window_tokens &&

package/src/core/governor/adapter-spread.ts

@@ -0,0 +1,82 @@
+/**
+ * Preflight: would every specialist on this team land on the same adapter?
+ *
+ * Harnery does not auto-spread. A specialist without an `adapter` pin inherits
+ * the run's default, so a team whose profiles all omit the pin puts every child
+ * on one adapter. That is legal and sometimes intended. It is a problem when the
+ * host is also `subscriptionOnly`, because then the concentration lands on one
+ * seat's session meter rather than on metered per-token billing: the seat hits
+ * its limit, and every specialist stops at once rather than the team degrading.
+ *
+ * The check is deliberately narrow, because a false refusal here is worse than
+ * the miss it prevents. It fires only when all four hold:
+ *
+ *   1. more than one specialist (a solo team cannot spread),
+ *   2. every specialist resolves to the same adapter,
+ *   3. `subscriptionOnly` is on (otherwise concentration is a cost curve, not a
+ *      cliff), and
+ *   4. more than one adapter is ATTESTED REACHABLE.
+ *
+ * Condition 4 is the one worth insisting on. Counting *declared* adapters would
+ * suggest spreading onto a seat that cannot run — a dead adapter passes a
+ * declaration check and then fails every child it is handed. Only an
+ * attestation records that the adapter actually completed a turn on this
+ * machine, so only an attestation is grounds for telling someone to use it.
+ */
+
+export interface AdapterSpreadInput {
+  /** Specialist id → its optional adapter pin. */
+  specialists: Readonly<Record<string, { adapter?: string }>>;
+  /** The adapter an unpinned specialist inherits. */
+  defaultAdapter: string;
+  /** Adapters with a live attestation on this machine — proven to run, not
+   * merely registered. */
+  reachable: readonly string[];
+  /** Whether children are confined to subscription (logged-in) auth. */
+  subscriptionOnly: boolean;
+}
+
+export interface AdapterSpreadVerdict {
+  /** True when the team would put every child on one adapter AND that is worth
+   * refusing over. False both when the team spreads and when concentrating is
+   * unremarkable (single specialist, one reachable adapter, metered billing). */
+  concentrated: boolean;
+  /** The adapter everything would land on, when concentrated. */
+  adapter?: string;
+  /** Operator-facing explanation, present exactly when concentrated. */
+  reason?: string;
+  /** Attested-reachable adapters this team is not using. */
+  unused: string[];
+}
+
+export function inspectAdapterSpread(input: AdapterSpreadInput): AdapterSpreadVerdict {
+  const ids = Object.keys(input.specialists);
+  const resolved = ids.map((id) => input.specialists[id]?.adapter ?? input.defaultAdapter);
+  const distinct = [...new Set(resolved)];
+  const unused = input.reachable.filter((a) => !distinct.includes(a));
+
+  if (ids.length < 2 || distinct.length !== 1 || !input.subscriptionOnly || unused.length === 0) {
+    return { concentrated: false, unused };
+  }
+
+  const adapter = distinct[0] as string;
+  const pinned = ids.filter((id) => input.specialists[id]?.adapter).length;
+  // Say which of the two shapes this is. "You wrote no pins" and "you pinned
+  // them all to one" need different corrections, and a single generic message
+  // would send half the readers looking in the wrong place.
+  const how =
+    pinned === 0
+      ? `no specialist pins an adapter, so all ${ids.length} inherit the default (${adapter})`
+      : `all ${ids.length} specialists resolve to ${adapter}`;
+  return {
+    concentrated: true,
+    adapter,
+    unused,
+    reason:
+      `${how}, and children are confined to subscription auth — so one seat carries the whole ` +
+      `team and every specialist stops together when it hits its limit. ` +
+      `${unused.length === 1 ? "This adapter is" : "These adapters are"} attested and idle: ` +
+      `${unused.join(", ")}. Pin some specialists onto ${unused.length === 1 ? "it" : "them"}, ` +
+      `or pass --allow-single-adapter if one seat is what you want.`,
+  };
+}

package/src/core/governor/index.ts

@@ -0,0 +1,91 @@
+export {
+  approveGovernorPlan,
+  findCompletedMissionGoverning,
+  rejectGovernorPlan,
+  reopenGovernorMission,
+  retryGovernorPlan,
+} from "./plan-api.ts";
+export {
+  readGovernorPlan,
+  readGovernorPlanReviewReceipt,
+  readGovernorPlans,
+} from "./plan-read.ts";
+export {
+  type CreateGovernorPlanTemplateInput,
+  type CreateGovernorReplanningInput,
+  GOVERNOR_PLAN_SCHEMA_VERSION,
+  type GovernorPlanEvent,
+  type GovernorPlanEventType,
+  type GovernorPlanHistory,
+  type GovernorPlanMilestone,
+  type GovernorPlanOutcome,
+  type GovernorPlanProposal,
+  type GovernorPlanRecord,
+  type GovernorPlanRequest,
+  type GovernorPlanReviewFinding,
+  type GovernorPlanReviewReceipt,
+  type GovernorPlanReviewReviewer,
+  type GovernorPlanReviewRound,
+  type GovernorPlanReviewStatus,
+  type GovernorPlanReviewSummary,
+  type GovernorPlanReviewVerdict,
+  type GovernorPlanStatus,
+  type GovernorPlanTemplate,
+  type GovernorPlanWorkSpec,
+  type GovernorReplanningPolicy,
+  MAX_GOVERNOR_PLAN_REVIEWERS,
+  MAX_GOVERNOR_PLAN_REVISION_ROUNDS,
+} from "./plan-types.ts";
+export {
+  type GovernorDispatchOutcome,
+  type GovernorRunReport,
+  type GovernorStopReason,
+  type RunGovernorInput,
+  runGovernor,
+} from "./runner.ts";
+export {
+  type ConfigureGovernorServiceInput,
+  configureGovernorService,
+  GOVERNOR_SERVICE_CONFIG_SCHEMA_VERSION,
+  GOVERNOR_SERVICE_RUNTIME_SCHEMA_VERSION,
+  GOVERNOR_SERVICE_STATUS_SCHEMA_VERSION,
+  type GovernorServiceConfig,
+  type GovernorServiceEngineConfig,
+  type GovernorServiceGoalRuntime,
+  type GovernorServiceGoalState,
+  type GovernorServiceProcessState,
+  type GovernorServiceRuntime,
+  type GovernorServiceStatus,
+  type GovernorServiceStatusRecord,
+  type GovernorServiceSweepOutcome,
+  type GovernorServiceSweepReport,
+  governorServiceLogPath,
+  type RunGovernorServiceDaemonInput,
+  type RunGovernorServiceSweepInput,
+  readGovernorServiceConfig,
+  readGovernorServiceRuntime,
+  readGovernorServiceStatus,
+  requestGovernorServiceStop,
+  runGovernorServiceDaemon,
+  runGovernorServiceSweep,
+  spawnGovernorService,
+} from "./service.ts";
+export {
+  assertGovernorId,
+  type CreateGovernorInput,
+  type CreateGovernorMissionInput,
+  collectGovernorWork,
+  createGovernor,
+  GOVERNOR_INTENT_SCHEMA_VERSION,
+  type GovernorAutomationPolicy,
+  type GovernorIntent,
+  type GovernorLimits,
+  type GovernorMission,
+  type GovernorNextAction,
+  type GovernorProjection,
+  type GovernorRecord,
+  type GovernorState,
+  listGovernors,
+  newGovernorId,
+  readGovernor,
+} from "./state.ts";

package/src/core/governor/plan-api.ts

@@ -0,0 +1,115 @@
+import type { GovernorPlanOutcome } from "./plan-types.ts";
+import {
+  applyGovernorPlanProposal,
+  rejectGovernorPlanProposal,
+  reopenGovernorMissionPlan,
+  retryGovernorPlanProposal,
+} from "./planning.ts";
+import { acquireGovernorLease, listGovernors, readGovernorIgnoringLease } from "./state.ts";
+
+export function approveGovernorPlan(input: {
+  coordRoot: string;
+  goalId: string;
+  planId: string;
+  actor?: string;
+  reason?: string;
+}): GovernorPlanOutcome {
+  const actor = input.actor?.trim() || `governor:${input.goalId}`;
+  const release = acquireGovernorLease(input.coordRoot, input.goalId);
+  try {
+    return applyGovernorPlanProposal({
+      coordRoot: input.coordRoot,
+      record: readGovernorIgnoringLease(input.coordRoot, input.goalId),
+      planId: input.planId,
+      actor,
+      reason: input.reason,
+    });
+  } finally {
+    release();
+  }
+}
+
+export function rejectGovernorPlan(input: {
+  coordRoot: string;
+  goalId: string;
+  planId: string;
+  actor?: string;
+  reason: string;
+}): GovernorPlanOutcome {
+  const actor = input.actor?.trim() || `governor:${input.goalId}`;
+  const release = acquireGovernorLease(input.coordRoot, input.goalId);
+  try {
+    return rejectGovernorPlanProposal({
+      coordRoot: input.coordRoot,
+      goalId: input.goalId,
+      planId: input.planId,
+      actor,
+      reason: input.reason,
+    });
+  } finally {
+    release();
+  }
+}
+
+/** The goal of a succeeded mission that governs this work item, if there is one.
+ *
+ * A work item holds no back-reference to its goal, so this is a scan. It exists so
+ * `work reopen` can tell the difference between an item nothing is watching and one
+ * whose mission has already been declared complete — the case where reopening the
+ * item alone leaves it in `ready_work` that the governor will never dispatch. */
+export function findCompletedMissionGoverning(
+  coordRoot: string,
+  workId: string,
+): string | undefined {
+  for (const record of listGovernors(coordRoot)) {
+    if (record.projection.state !== "succeeded" || !record.intent.mission) continue;
+    if (record.projection.root_work_id === workId || record.projection.work_ids.includes(workId)) {
+      return record.intent.id;
+    }
+  }
+  return undefined;
+}
+
+/** ADR 0050: reopen an accepted mission completion by appending to the plan log.
+ * Held under the goal lease so it cannot race a foreground governor run. */
+export function reopenGovernorMission(input: {
+  coordRoot: string;
+  goalId: string;
+  actor?: string;
+  reason: string;
+}): GovernorPlanOutcome {
+  const actor = input.actor?.trim() || `governor:${input.goalId}`;
+  const release = acquireGovernorLease(input.coordRoot, input.goalId);
+  try {
+    return reopenGovernorMissionPlan({
+      coordRoot: input.coordRoot,
+      record: readGovernorIgnoringLease(input.coordRoot, input.goalId),
+      actor,
+      reason: input.reason,
+    });
+  } finally {
+    release();
+  }
+}
+
+export function retryGovernorPlan(input: {
+  coordRoot: string;
+  goalId: string;
+  planId: string;
+  actor?: string;
+  reason: string;
+}): GovernorPlanOutcome {
+  const actor = input.actor?.trim() || `governor:${input.goalId}`;
+  const release = acquireGovernorLease(input.coordRoot, input.goalId);
+  try {
+    return retryGovernorPlanProposal({
+      coordRoot: input.coordRoot,
+      record: readGovernorIgnoringLease(input.coordRoot, input.goalId),
+      planId: input.planId,
+      actor,
+      reason: input.reason,
+    });
+  } finally {
+    release();
+  }
+}