openmerit 0.1.12 → 0.3.0

package/dist/terminal/src/updates.ts

@@ -1,313 +0,0 @@
-// Standalone updater copied into Claude's configuration directory. Only Node
-// built-ins: it must survive the npx cache disappearing, without installing or
-// executing code from the release it downloads.
-import { createHash, randomUUID } from 'node:crypto';
-import { realpathSync } from 'node:fs';
-import { mkdir, open, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
-import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { gunzipSync } from 'node:zlib';
-
-type ObjectValue = Record<string, unknown>;
-interface Bundle { format: number; contract: string; version: string; skill: string; rule: string }
-interface UpdateRecord { enabled: boolean; version: string; runnerHash: string; hook: ObjectValue }
-export const updateContract = 'scout-recommend-v1';
-const registry = 'https://registry.npmjs.org/openmerit/latest';
-const day = 24 * 60 * 60 * 1000;
-const retry = 15 * 60 * 1000;
-const digest = (text: string | Buffer) => createHash('sha256').update(text).digest('hex');
-const isObject = (value: unknown): value is ObjectValue => !!value && typeof value === 'object' && !Array.isArray(value);
-const parsed = (text: string): ObjectValue => {
-  const value: unknown = JSON.parse(text);
-  if (!isObject(value)) throw new Error('Expected a JSON object.');
-  return value;
-};
-async function optional(path: string): Promise<string | null> {
-  try { return await readFile(path, 'utf8'); }
-  catch (error) { if (isObject(error) && error.code === 'ENOENT') return null; throw error; }
-}
-async function object(path: string): Promise<ObjectValue> { return parsed(await optional(path) ?? '{}'); }
-async function atomic(path: string, value: unknown) {
-  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
-  const temp = `${path}.${randomUUID()}.tmp`;
-  try {
-    await writeFile(temp, typeof value === 'string' ? value : `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
-    await rename(temp, path);
-  } finally { await rm(temp, { force: true }); }
-}
-export function updatePaths(base: string, scope: string) {
-  return {
-    record: join(base, 'openmerit-install.json'), runner: join(base, 'openmerit-updater.mts'),
-    settings: join(base, scope === 'user' ? 'settings.json' : 'settings.local.json'),
-    state: join(base, 'openmerit-updates.json'), backup: join(base, 'openmerit-update-backup.json'),
-    skill: join(base, 'skills/openmerit-scout/SKILL.md'), rule: join(base, 'rules/openmerit-scout.md'),
-  };
-}
-function updateRecord(record: ObjectValue): UpdateRecord | null {
-  const value = record.updates;
-  if (!isObject(value) || typeof value.enabled !== 'boolean' || typeof value.version !== 'string'
-    || typeof value.runnerHash !== 'string' || !isObject(value.hook)) return null;
-  return value as unknown as UpdateRecord;
-}
-
-// Serialize installs, removals and hooks. A dead process's lock is recoverable;
-// an active login is not mistaken for a stale updater just because it is slow.
-export async function withUpdateLock<T>(base: string, work: () => Promise<T>): Promise<T> {
-  await mkdir(base, { recursive: true, mode: 0o700 });
-  const path = join(base, 'openmerit-update.lock');
-  let handle;
-  for (let attempt = 0; attempt < 2; attempt++) {
-    try { handle = await open(path, 'wx', 0o600); break; }
-    catch (error) {
-      if (!isObject(error) || error.code !== 'EEXIST') throw error;
-      // Only one process may reap a dead lock. Without this guard, two stale
-      // observers can unlink each other's newly acquired live lock.
-      const recoveryPath = `${path}.recovery`;
-      let recovery;
-      try { recovery = await open(recoveryPath, 'wx', 0o600); }
-      catch { throw new Error('Another OpenMerit lock recovery is running. If it was interrupted, review openmerit-update.lock.recovery before removing it.'); }
-      try {
-        await recovery.writeFile(JSON.stringify({ pid: process.pid }));
-        const text = await optional(path);
-        if (text === null) continue;
-        let alive = true;
-        try {
-          const pid = parsed(text).pid;
-          if (typeof pid === 'number' && pid > 0) {
-            try { process.kill(pid, 0); }
-            catch (failure) { if (isObject(failure) && failure.code === 'ESRCH') alive = false; }
-          } else alive = Date.now() - (await stat(path)).mtimeMs < 10 * 60_000;
-        } catch { alive = Date.now() - (await stat(path)).mtimeMs < 10 * 60_000; }
-        if (alive) throw new Error('Another OpenMerit install or update is running. Retry shortly.');
-        await rm(path, { force: true });
-      } finally { await recovery.close(); await rm(recoveryPath, { force: true }); }
-    }
-  }
-  if (!handle) throw new Error('Another OpenMerit update is running.');
-  try { await handle.writeFile(JSON.stringify({ pid: process.pid })); return await work(); }
-  finally { await handle.close(); await rm(path, { force: true }); }
-}
-
-function groups(settings: ObjectValue): ObjectValue {
-  if (settings.hooks === undefined) return {};
-  if (!isObject(settings.hooks)) throw new Error('Claude settings.hooks is not an object; nothing changed.');
-  return settings.hooks;
-}
-function eventGroups(hooks: ObjectValue, event: string): unknown[] {
-  const value = hooks[event];
-  if (value === undefined) return [];
-  if (!Array.isArray(value)) throw new Error(`Claude ${event} hooks are not an array; nothing changed.`);
-  return value;
-}
-function usesRunner(group: unknown, runner: string): boolean {
-  return isObject(group) && Array.isArray(group.hooks) && group.hooks.some(hook =>
-    isObject(hook) && typeof hook.command === 'string' && (hook.command.includes(runner) || hook.command.includes(quote(runner))));
-}
-export async function inspectUpdates(base: string, scope: string, record: ObjectValue) {
-  const paths = updatePaths(base, scope), saved = updateRecord(record);
-  const pending = updateRecord({ updates: record.pendingUpdates });
-  const owners = [saved, pending].filter(value => value !== null);
-  const runner = await optional(paths.runner), settings = await object(paths.settings), hooks = groups(settings);
-  const conflicts: string[] = [];
-  if (runner !== null && !owners.some(owner => digest(runner) === owner.runnerHash)) conflicts.push('OpenMerit updater was edited or is not owned; nothing changed.');
-  for (const event of ['SessionStart', 'Stop']) {
-    for (const group of eventGroups(hooks, event)) {
-      if (usesRunner(group, paths.runner) && !owners.some(owner => JSON.stringify(group) === JSON.stringify(owner.hook))) {
-        conflicts.push(`OpenMerit ${event} hook was edited or is not owned; nothing changed.`);
-      }
-    }
-  }
-  const active = runner !== null && ['SessionStart', 'Stop'].every(event =>
-    eventGroups(hooks, event).some(group => owners.some(owner => JSON.stringify(group) === JSON.stringify(owner.hook))));
-  return { paths, saved: saved ?? pending, runner, settings, hooks, conflicts, active };
-}
-// Claude Code uses a shell for command hooks, including Git Bash on Windows.
-const quote = (value: string) => `'${value.replaceAll("'", "'\"'\"'")}'`;
-export async function configureUpdates(base: string, scope: string, record: ObjectValue, version: string, enabled: boolean) {
-  const state = await inspectUpdates(base, scope, record);
-  if (state.conflicts.length) throw new Error(state.conflicts.join('\n'));
-  const source = await readFile(new URL('./updates.ts', import.meta.url), 'utf8');
-  const hook = { hooks: [{ type: 'command', command: `${quote(process.execPath)} ${quote(state.paths.runner)} --base ${quote(base)} --scope ${scope} --hook`, async: true, timeout: 150 }] };
-  const hooks = { ...state.hooks };
-  for (const event of ['SessionStart', 'Stop']) {
-    const kept = eventGroups(hooks, event).filter(group => !usesRunner(group, state.paths.runner));
-    if (enabled) kept.push(hook);
-    if (kept.length) hooks[event] = kept; else delete hooks[event];
-  }
-  // Avoid clobbering settings that changed while the installer was signing in.
-  const latest = await object(state.paths.settings);
-  if (JSON.stringify(latest) !== JSON.stringify(state.settings)) throw new Error('Claude settings changed during setup. Retry.');
-  const next = { enabled, version, runnerHash: digest(source), hook };
-  await atomic(state.paths.record, { ...await object(state.paths.record), pendingUpdates: next });
-  await atomic(state.paths.runner, source);
-  await atomic(state.paths.settings, { ...state.settings, hooks });
-  return next;
-}
-export async function removeUpdates(base: string, scope: string, record: ObjectValue) {
-  const state = await inspectUpdates(base, scope, record);
-  const hooks = { ...state.hooks };
-  for (const event of ['SessionStart', 'Stop']) {
-    const kept = eventGroups(hooks, event).filter(group => !state.saved || JSON.stringify(group) !== JSON.stringify(state.saved.hook));
-    if (kept.length) hooks[event] = kept; else delete hooks[event];
-  }
-  if (state.saved) await atomic(state.paths.settings, { ...state.settings, hooks });
-  const stillReferenced = ['SessionStart', 'Stop'].some(event => eventGroups(hooks, event).some(group => usesRunner(group, state.paths.runner)));
-  if (!stillReferenced && state.runner !== null && state.saved && digest(state.runner) === state.saved.runnerHash) await rm(state.paths.runner, { force: true });
-  await rm(state.paths.state, { force: true });
-}
-
-// Read one fixed regular file in memory, never extract archive paths onto disk.
-function instructionBundle(bytes: Buffer): ObjectValue | null {
-  const tar = gunzipSync(bytes, { maxOutputLength: 32 * 1024 * 1024 });
-  let found: ObjectValue | null = null;
-  for (let offset = 0; offset + 512 <= tar.length;) {
-    const header = tar.subarray(offset, offset + 512);
-    if (header.every(byte => byte === 0)) break;
-    const name = header.subarray(0, 100).toString().replace(/\0.*$/s, '');
-    const rawSize = header.subarray(124, 136).toString().replace(/\0.*$/s, '').trim();
-    if (!/^[0-7]+$/.test(rawSize)) throw new Error('Invalid package archive.');
-    const size = Number.parseInt(rawSize, 8), start = offset + 512;
-    if (start + size > tar.length) throw new Error('Truncated package archive.');
-    if (name === 'package/dist/terminal/scout-update.json') {
-      if (found || size > 256 * 1024 || ![0, 48].includes(header[156] ?? -1)) throw new Error('Invalid instruction bundle.');
-      found = parsed(tar.subarray(start, start + size).toString('utf8'));
-    }
-    offset = start + Math.ceil(size / 512) * 512;
-  }
-  return found;
-}
-const stableVersion = (version: string) => /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.test(version);
-function newer(next: string, installed: string) {
-  if (!stableVersion(next) || !stableVersion(installed)) return false;
-  const a = next.split('.').map(Number), b = installed.split('.').map(Number);
-  for (let i = 0; i < 3; i++) { if (a[i] !== b[i]) return a[i]! > b[i]!; }
-  return false;
-}
-async function boundedFetch(url: string, max: number, fetcher: typeof fetch, timeout = 12_000): Promise<Buffer> {
-  const controller = new AbortController();
-  let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
-  let timer: ReturnType<typeof setTimeout> | undefined;
-  const deadline = new Promise<never>((_, reject) => {
-    timer = setTimeout(() => { controller.abort(); reject(new Error('Update download timed out.')); }, timeout);
-  });
-  const download = async () => {
-    const response = await fetcher(url, { redirect: 'error', signal: controller.signal, headers: { Accept: 'application/json' } });
-    if (!response.ok || !response.body || controller.signal.aborted) throw new Error('Update server unavailable.');
-    const parts: Uint8Array[] = []; let size = 0;
-    reader = response.body.getReader();
-    for (;;) {
-      const { value, done } = await reader.read();
-      if (done) break;
-      size += value.length;
-      if (size > max) throw new Error('Update download exceeded its size limit.');
-      parts.push(value);
-    }
-    return Buffer.concat(parts);
-  };
-  try {
-    return await Promise.race([download(), deadline]);
-  } finally {
-    clearTimeout(timer); controller.abort();
-    // Cancellation itself must not keep a timed-out hook alive.
-    void reader?.cancel().catch(() => {});
-  }
-}
-async function recover(base: string, scope: string) {
-  const paths = updatePaths(base, scope), text = await optional(paths.backup);
-  if (!text) return;
-  const backup = parsed(text);
-  if (typeof backup.skill !== 'string' || typeof backup.rule !== 'string' || !isObject(backup.record)) throw new Error('Update recovery needs manual review.');
-  for (const field of ['skill', 'rule'] as const) {
-    const current = await optional(paths[field]);
-    if (current !== null && digest(current) !== digest(backup[field] as string) && digest(current) !== backup[`${field}Hash`]) throw new Error('An interrupted update has user edits; nothing changed.');
-  }
-  // Recover the previous complete pair before any retry. Atomic per-file writes
-  // plus a durable journal cover failure between the two renames.
-  await atomic(paths.skill, backup.skill); await atomic(paths.rule, backup.rule);
-  await atomic(paths.record, backup.record); await rm(paths.backup, { force: true });
-}
-export async function recoverUpdates(base: string, scope: string) { await recover(base, scope); }
-
-export interface UpdateResult { status: string; message: string; version?: string }
-export async function runUpdate(base: string, scope: string, options: { hook?: boolean; enabled?: boolean; fetcher?: typeof fetch; now?: number } = {}): Promise<UpdateResult> {
-  return withUpdateLock(base, async () => {
-    await recover(base, scope);
-    const paths = updatePaths(base, scope), record = await object(paths.record), saved = updateRecord(record);
-    if (record.version !== 3 || record.scope !== scope || !saved) return { status: 'manual_required', message: 'Run npx -y openmerit@latest install --client claude-code to bootstrap updates in this scope.' };
-    if (options.hook && (!saved.enabled || process.env.OPENMERIT_AUTO_UPDATE === 'off')) return { status: 'disabled', message: 'Automatic updates disabled.' };
-    const now = options.now ?? Date.now(), state = options.enabled === undefined ? await object(paths.state) : {};
-    if (options.hook && typeof state.nextCheckAt === 'number' && now < state.nextCheckAt) return { status: 'not_due', message: 'Update check not due.' };
-    const support = await inspectUpdates(base, scope, record);
-    if (support.conflicts.length) {
-      if (options.hook) await atomic(paths.state, { nextCheckAt: now + day, status: 'conflict' });
-      return { status: 'conflict', message: `${support.conflicts.join(' ')} Say “update openmerit” after resolving the conflict.` };
-    }
-    if (options.enabled !== undefined) {
-      record.updates = await configureUpdates(base, scope, record, saved.version, options.enabled);
-      delete record.pendingUpdates;
-      await atomic(paths.record, record);
-      return { status: options.enabled ? 'enabled' : 'disabled', message: `Automatic Scout instruction updates ${options.enabled ? 'enabled' : 'disabled'}. Start a new Claude Code session to reload hooks.` };
-    }
-    // Record the attempt before networking so a crashed hook cannot hammer npm.
-    await atomic(paths.state, { ...state, nextCheckAt: now + retry });
-    try {
-      const fetcher = options.fetcher ?? fetch;
-      const release = parsed((await boundedFetch(registry, 512 * 1024, fetcher)).toString('utf8'));
-      const version = release.version;
-      if (release.name !== 'openmerit' || typeof version !== 'string' || !stableVersion(version)) throw new Error('Invalid stable release metadata.');
-      if (!newer(version, saved.version)) {
-        await atomic(paths.state, { checkedAt: now, nextCheckAt: now + day, status: 'current' });
-        return { status: 'current', version: saved.version, message: `Scout instructions ${saved.version} are current.` };
-      }
-      const dist = release.dist;
-      const tarball = `https://registry.npmjs.org/openmerit/-/openmerit-${version}.tgz`;
-      if (!isObject(dist) || dist.tarball !== tarball || typeof dist.integrity !== 'string' || !/^sha512-[A-Za-z0-9+/]+={0,2}$/.test(dist.integrity)) throw new Error('Release has no trusted SHA-512 package integrity.');
-      const bytes = await boundedFetch(tarball, 16 * 1024 * 1024, fetcher, 120_000);
-      if (`sha512-${createHash('sha512').update(bytes).digest('base64')}` !== dist.integrity) throw new Error('Package integrity verification failed.');
-      const bundle = instructionBundle(bytes);
-      if (!bundle || bundle.format !== 1 || bundle.contract !== updateContract || bundle.version !== version) {
-        await atomic(paths.state, { checkedAt: now, nextCheckAt: now + day, status: 'manual_required' });
-        return { status: 'manual_required', version, message: `Release ${version} needs a reviewed installer upgrade. Review its changes, then run npx -y openmerit@latest install --client claude-code --scope ${scope}. Do not bypass permissions or rerun login automatically.` };
-      }
-      if (typeof bundle.skill !== 'string' || typeof bundle.rule !== 'string' || !bundle.skill.startsWith('---\nname: openmerit-scout\n') || !bundle.rule.trim()) throw new Error('Invalid Scout instructions.');
-      const instructions = bundle as unknown as Bundle;
-      const skill = await optional(paths.skill), rule = await optional(paths.rule);
-      if (skill === null || rule === null || digest(skill) !== record.skillHash || digest(rule) !== record.ruleHash) {
-        await atomic(paths.state, { checkedAt: now, nextCheckAt: now + day, status: 'conflict' });
-        return { status: 'conflict', message: 'Scout instructions are missing or edited. Nothing changed. Say “update openmerit” after reviewing the files.' };
-      }
-      const skillHash = digest(instructions.skill), ruleHash = digest(instructions.rule);
-      await atomic(paths.backup, { record, skill, rule, skillHash, ruleHash });
-      try {
-        // Do not overwrite edits made during the download or journal write.
-        if (await optional(paths.skill) !== skill || await optional(paths.rule) !== rule) throw new Error('Scout instructions changed during the update.');
-        await atomic(paths.skill, instructions.skill); await atomic(paths.rule, instructions.rule);
-        await atomic(paths.record, { ...record, skillHash, ruleHash, updates: { ...saved, version } });
-        await rm(paths.backup, { force: true });
-      } catch (error) {
-        try { await recover(base, scope); }
-        catch { return { status: 'conflict', message: 'An interrupted Scout update could not be recovered safely. Review the installed files and openmerit-update-backup.json; no user edits were overwritten.' }; }
-        throw error;
-      }
-      // A failed schedule write must not misreport an already applied update.
-      await atomic(paths.state, { checkedAt: now, nextCheckAt: now + day, status: 'updated', version }).catch(() => {});
-      return { status: 'updated', version, message: `Scout instructions updated to ${version}. Start a new Claude Code session to load them; the running session may still use its previous instructions.` };
-    } catch {
-      await atomic(paths.state, { nextCheckAt: now + retry, status: 'retry' });
-      return { status: 'retry', message: 'Could not safely update Scout. The installed version was retained. Automatic checks retry after 15 minutes while Claude Code is in use; say “update openmerit” to retry now.' };
-    }
-  });
-}
-
-// Hooks deliberately never ask Claude to continue, read transcripts or emit
-// blocking decisions. Offline and concurrent-hook failures exit successfully.
-if (process.argv[1] && realpathSync(resolve(process.argv[1])) === fileURLToPath(import.meta.url)) {
-  const args = process.argv.slice(2), base = args[args.indexOf('--base') + 1], scope = args[args.indexOf('--scope') + 1];
-  if (base && ['user', 'project'].includes(scope ?? '')) {
-    process.stdin.resume();
-    try {
-      const result = await runUpdate(resolve(base), scope!, { hook: args.includes('--hook') });
-      if (['updated', 'conflict', 'manual_required', 'retry'].includes(result.status)) console.log(JSON.stringify({ systemMessage: result.message }));
-    } catch { /* Maintenance cannot block the user's task. */ }
-  }
-}

package/docs/adapter-guide.md

@@ -1,191 +0,0 @@
-# Building a harness adapter
-
-**Evaluation coordinator boundary:** this guide remains applicable to custom harnesses. Pi-specific examples refer to the historical Pi 0.87 evaluation adapter. The unreleased Pi 1.5.0 `openmerit/pi` export is instead a thin Scout adapter and does not implement `HarnessAdapter`; see [native MCP and SDK embedding](pi-extension.md#sdk-embedding).
-
-OpenMerit adapters are transport bridges. They do not reproduce OpenMerit's lifecycle, validation, persistence, or Pareto rules, and OpenMerit does not reproduce the harness's intelligence.
-
-## Required components
-
-An adapter provides a `HarnessAdapter` with:
-
-- a stable harness descriptor;
-- the OpenMerit protocol versions it supports;
-- declared capabilities;
-- supported execution modes;
-- a `dispatch` method that accepts a canonical `OpenMeritIntent` and returns an acceptance receipt.
-
-```ts
-import {
-  OpenMeritCoordinator,
-  ProjectStore,
-  type HarnessAdapter,
-} from "openmerit/core";
-import { PROTOCOL_VERSION, OPENMERIT_SCHEMA_DIALECT } from "openmerit/protocol";
-
-const adapter: HarnessAdapter = {
-  descriptor: {
-    id: "my-harness",
-    name: "My coding harness",
-    version: "1.0.0",
-    protocolVersions: [PROTOCOL_VERSION],
-    capabilities: [
-      "user_confirmation",
-      "evaluation_authoring",
-      "observability_instrumentation",
-      "production_observation",
-      "candidate_discovery",
-      "challenger_execution",
-      "frontier_calculation",
-      "model_mutation",
-      "post_swap_verification",
-      "rollback",
-    ],
-    executionModes: ["interactive"],
-    structuredOutput: {
-      schemaDialect: OPENMERIT_SCHEMA_DIALECT,
-      presentation: "adapter_validation",
-      enforcement: "adapter",
-    },
-    automation: {
-      supportedSignals: ["product_task_completed", "metric_window_available", "scheduled_tick", "model_catalog_changed", "verification_window_completed"],
-      persistentScheduling: false,
-      backgroundExecution: false,
-      wakeupProvisioning: "none",
-    },
-  },
-  async dispatch(intent) {
-    await myHarness.enqueue(intent);
-    return { accepted: true, harnessJobId: intent.id };
-  },
-};
-
-const coordinator = new OpenMeritCoordinator(
-  new ProjectStore(process.cwd()),
-  adapter,
-);
-```
-
-`ProjectStore` is the included local-filesystem backend. A remote or hosted integration can implement the `OpenMeritStore` interface instead.
-
-The confirmed task profile identifies the application LLM call under evaluation. Every metric, assessment, candidate, frontier artifact, and automation signal must carry that target ID; the harness's own model usage is orchestration data and must not be reported as product evidence. Application-provider cost, token, and latency telemetry belongs on the application signal or metric record.
-
-Setup may return `preliminaryModelLeads`: model IDs with sourced price estimates and reputation summaries. The field is optional under protocol 0.1 for older adapters. Core stores the leads and includes both the confirmed task profile and these leads in later discovery intent constraints, so a headless harness run does not depend on prior chat context. Leads are research priors, never measured candidate assessments.
-
-## External telemetry export
-
-OpenMerit always writes its canonical, redacted audit stream locally. A host integration may pass `eventExporters` to `ProjectStore` to mirror those same safe events to OpenTelemetry, Langfuse, LangSmith, or another observability backend:
-
-```ts
-const store = new ProjectStore(projectRoot, {
-  eventExporters: [{
-    id: "my-otel-bridge",
-    async export(event) {
-      await telemetry.emit("openmerit.audit", event);
-    },
-  }],
-});
-```
-
-Exporters are not the durable source of truth. They are best effort, and failures are recorded locally without blocking OpenMerit decisions.
-
-## Dispatching work
-
-```ts
-const issued = await coordinator.issue("establish_evals");
-```
-
-The coordinator builds the canonical intent, checks the descriptor's protocol and capabilities, creates durable state, records audit events, and calls the adapter. The harness decides how to execute the job.
-
-If a required capability is absent, dispatch is rejected before harness work starts.
-
-## Reporting progress
-
-A harness may send durable lifecycle progress through `recordLifecycle`:
-
-```ts
-await coordinator.recordLifecycle({
-  protocolVersion: PROTOCOL_VERSION,
-  intentId: issued.intent.id,
-  status: "running",
-  occurredAt: new Date().toISOString(),
-  message: "Generating representative evaluation cases",
-});
-```
-
-Use `waiting_for_user` when an interactive confirmation is required but cannot be completed in the current execution mode.
-
-## Completing work
-
-Each intent kind has a typed output in `IntentOutputMap`. Return an `IntentResult<K>` with durable evidence references, then submit it to the coordinator:
-
-```ts
-await coordinator.acceptResult(result);
-```
-
-The coordinator validates the active intent, protocol version, evidence references, and intent-specific output, including applicable frontier and candidate-identity checks, before updating lifecycle state. Adapters must not duplicate this logic. The harness remains responsible for performing only the authorized work; result validation does not sandbox its tools or authenticate external evidence.
-
-### Present the canonical result schema
-
-Import `completionToolSchemaFor(intent.kind)` from `openmerit/protocol` and present it through the harness's strongest structured-output mechanism. Do not recreate result schemas inside an adapter. A harness that supports changing tool definitions should specialize the completion tool whenever an intent becomes active; other harnesses may expose intent-specific tools or perform adapter-side validation.
-
-Declare the behavior in `HarnessDescriptor.structuredOutput`:
-
-- `schemaDialect` identifies the canonical OpenMerit JSON Schema dialect;
-- `presentation` states whether the adapter uses a dynamic tool, a static union, or adapter validation;
-- `enforcement` states whether validation occurs at the provider and harness, harness only, or adapter only.
-
-Schema validation catches malformed structure. The coordinator still owns semantic checks such as authorized candidate identity, metric readiness for frontier comparisons, lifecycle consistency, and Pareto conformance.
-
-## Reporting normal work and catalogue changes
-
-After a real product task completes:
-
-```ts
-await coordinator.recordTaskObservation({
-  modelId: "vendor/model",
-});
-
-// Core has already checked baseline
-// sufficiency when the confirmed cadence became due. Inspect durable state
-// and dispatch only a pending downstream intent, if any.
-```
-
-`recordTaskObservation` resolves the confirmed application target from project state. New adapters should prefer `recordAutomationSignal` so the task signal can carry the explicit `targetId`, durable evidence, and application-provider telemetry.
-
-When the harness's available model catalogue changes, compute a stable fingerprint and call `recordModelCatalogFingerprint`. The returned `reassessmentDue` flag tells the adapter whether the lifecycle justifies candidate discovery.
-
-New adapters should use `recordAutomationSignal` for product tasks, metric windows, scheduled ticks, catalogue observations, and verification windows. Signal IDs must remain stable across delivery retries. If the returned decision issues an intent, dispatch it through the coordinator. `recordTaskObservation` and `recordModelCatalogFingerprint` remain compatibility helpers.
-
-Call `reconcileAutomation` after configuration changes or when restoring a project. It returns an `AutomationPlan`. Implement `scheduleWakeup` only when the harness can genuinely arrange the requested wakeup. Declare persistent scheduling, background execution, supported signal sources, and provisioning requirements accurately in `HarnessDescriptor.automation`.
-
-If persistent scheduling is unavailable, expose the plan's active-session or external-scheduler fallback. Do not report a seven-day schedule as configured merely because the adapter checks policy when an interactive session starts.
-
-## Capability mapping
-
-| Intent | Required capability |
-| --- | --- |
-| `establish_evals` | confirmation, evaluation authoring, observability instrumentation |
-| `instrument_observability` | observability instrumentation |
-| `run_assessment` | production observation |
-| `discover_candidates` | candidate discovery |
-| `run_challenger_trials` | challenger execution |
-| `calculate_frontier` | frontier calculation |
-| `investigate_regression` | production observation |
-| `apply_model_swap` | model mutation |
-| `verify_model_swap` | post-swap verification |
-| `rollback_model_swap` | rollback |
-
-## Conformance checklist
-
-An adapter is ready when it:
-
-1. advertises only capabilities it can actually execute;
-2. preserves intent IDs and protocol versions;
-3. never reports success without durable evidence;
-4. returns the typed output for every supported intent;
-5. performs model mutation only when the intent explicitly authorizes it;
-6. reports ordinary product tasks without counting OpenMerit orchestration turns;
-7. passes a durable issue-and-complete cycle using `OpenMeritCoordinator`;
-8. proves the requested side effect, not merely a generated description.
-
-The fake non-Pi adapter in `packages/core/test/adapter-conformance.test.ts` is the executable reference.

package/docs/architecture.md

@@ -1,61 +0,0 @@
-# Architecture
-
-**Source status:** the Pi 1.5.0 native Scout replacement is unreleased and unpublished. The protocol/core evaluation coordinator described here remains available for custom harnesses; it is not invoked by the new Pi adapter. The standalone evaluation CLI and Inference Terminal are unchanged.
-
-## Design principle
-
-OpenMerit is an orchestrator, not an intelligence layer. The product application LLM call is the system under test; the coding harness is the evaluator and execution environment.
-
-```text
-User or lifecycle event
-        |
-        v
-OpenMerit deterministic orchestration
-        |
-        | typed intent: outcome, constraints, evidence
-        v
-Custom evaluation harness
-        |
-        | intelligent work, tools, evals, calculation
-        v
-Typed result and durable evidence references
-        |
-        v
-OpenMerit validation, policy, persistence, next nudge
-```
-
-An automatic OpenMerit action means automatic issuance of an approved intent. OpenMerit does not perform candidate research, evaluate quality, calculate a frontier, or mutate model configuration.
-
-## Packages
-
-### `openmerit/protocol`
-
-Defines the JSON-safe boundary: durable intents, evidence references, metrics, task profiles, candidate assessments, frontier snapshots, budgets, policies, state, and audit events.
-
-It also owns the versioned runtime schema registry for all intent results. Harness adapters consume these schemas rather than defining their own result shapes, report their structured-output capabilities, and may present the active schema using harness-native tools or adapter validation. A confirmed application LLM target is carried through profiles, metrics, candidates, frontier results, automation signals, and swaps; the harness model is not a valid substitute target.
-
-### `openmerit/core`
-
-Contains deterministic behavior: choosing the next lifecycle intent according to confirmation and rollback policy, persisting state, and checking harness-produced frontiers against the normative definition. The verifier rejects invalid harness results; it is not a model-selection engine.
-
-`OpenMeritCoordinator` is the reusable adapter boundary. It constructs canonical intents, negotiates capabilities, records lifecycle progress and observations, validates results, and advances durable state. `OpenMeritStore` makes persistence replaceable; `ProjectStore` is the bundled filesystem backend.
-
-The coordinator also accepts idempotent application-target automation signals and evaluates the user-confirmed `AutomationCheckPolicy`. `buildAutomationPlan` tells an adapter which signals and wakeups are required and reports unsupported persistent scheduling honestly. Provisioning belongs to a custom adapter; the coordinator itself does not create operating-system schedulers or paid cloud workers. The removed Pi 0.87 adapter's LaunchAgent is historical functionality, not part of the new Scout connection.
-
-### `openmerit/pi`
-
-Exports `createScoutPiExtension` and a default native Scout extension for Pi 1.5.0. It registers the authenticated Scout HTTP MCP server through Pi and adds shared rule/skill prompt sections. Pi owns discovery, tools, permissions, model and sessions; SDK hosts must load Pi's `createMcpExtension()` explicitly alongside it.
-
-The package no longer implements `HarnessAdapter`, exposes lifecycle commands, or schedules evaluation work. It shares credential and instruction code with the installer instead of duplicating an MCP client or evaluation coordinator. See [Pi installation and migration](pi-extension.md).
-
-### Inference Terminal
-
-`packages/terminal` supplies a standalone `openmerit dash` executable, passive collectors, a loopback read-only HTTP API, and bundled browser assets. Stable npm 0.1.6 includes the terminal. The source interface and hosted dashboard follow the device’s light/dark preference; that appearance change is not included in npm 0.1.6. It does not invoke the coordinator or harness. One collector cycle reads existing metadata and runtime inventory; browser clients receive the same cached snapshot. Imported activity, runtime counters, and sampled whole-machine resources retain their separate scopes. Missing measurements remain unknown, and fictional sample data is isolated from the real snapshot. See the [terminal guide](inference-terminal.md) for the supported sources and JSON contract.
-
-## Intelligence resources
-
-Models, web research, tools, evaluators, and fast decision systems such as Jev System One are harness resources. They are configured and invoked by the host harness. This keeps the coordinator provider-neutral and lets custom adapters choose their own implementation.
-
-## Trust boundary
-
-The harness is trusted to perform the work and return honest evidence. OpenMerit reduces unsupported claims through structured outputs, evidence references, compatible profile revisions, complete comparisons, and conservative uncertainty handling. It cannot prove that an arbitrary external evidence URI contains truthful data.

package/docs/automation.md

@@ -1,76 +0,0 @@
-# Harness-neutral automation
-
-**Core reference / historical Pi workflow:** the unreleased Pi 1.5.0 Scout adapter replaces the Pi 0.87 lifecycle adapter. It has no signals, `/openmerit` commands, scheduler, headless wakeups, or LaunchAgent. Pi-specific provisioning instructions below are historical, not available in the replacement. The coordinator's policy and signal APIs remain available to custom harnesses. See [current Pi setup and migration](pi-extension.md); the standalone [evaluation watcher](agent-evaluations.md) is unchanged.
-
-The user defines cadence, thresholds, budget, scheduling mode, and automation permission. OpenMerit stores that policy, evaluates durable signals, and decides whether a bounded intent is due. A harness adapter arranges native wakeups and reports events. The coding harness performs the resulting intelligent work.
-
-```text
-User-confirmed policy
-        ↓
-OpenMerit due-check engine
-        ↓
-Harness-native wakeup or lifecycle hook
-        ↓
-Standard automation signal
-        ↓
-No work due, or one typed OpenMerit intent
-```
-
-## Check policy
-
-`AutomationCheckPolicy` independently configures:
-
-- baseline assessment cadence;
-- frontier reassessment cadence and catalogue-change behavior;
-- regression-check cadence and per-metric relative deterioration thresholds;
-- post-swap verification windows;
-- a cooldown between mature-system checks;
-- active-session or persistent execution;
-- whether wakeup provisioning may make infrastructure changes.
-
-Task-count and elapsed-time triggers use OR semantics. A policy with `afterCompletedTasks: 100` and `afterElapsedSeconds: 604800` becomes due at the first threshold reached. A scheduled wakeup does not directly launch expensive work: it submits `scheduled_tick`, and OpenMerit evaluates policy and durable state before issuing an intent.
-
-The baseline elapsed-time clock starts when setup or required instrumentation finishes. Ordinary task and metric signals do not restart that clock. OpenMerit retains the latest reported aggregate window for each application metric, including sample count and evidence references. It never sums possibly overlapping windows. At a due baseline check, core requires ready instrumentation and a finite measured value, enough samples, and an evidence reference for every required objective. An insufficient check records the gaps and waits for more data; sufficient evidence advances to candidate discovery.
-
-## Signals
-
-Adapters may report:
-
-- `product_task_completed`;
-- `metric_window_available`;
-- `scheduled_tick`;
-- `model_catalog_changed`;
-- `verification_window_completed`.
-
-Signal IDs are idempotency keys. OpenMerit persists a bounded history, does not count duplicate task completions twice, and keeps due work pending until an adapter successfully dispatches it.
-
-## Capability negotiation
-
-Every `HarnessDescriptor` declares supported signals, persistent scheduling, background execution, and whether wakeup provisioning is native, unavailable, or requires an infrastructure change. OpenMerit produces an `AutomationPlan` containing required signals, the next wakeup, scheduling strategy, and explicit gaps.
-
-If persistent scheduling is requested but unsupported, the plan says `external_scheduler_required`. The adapter must not claim that a schedule exists. Active-session adapters can submit `scheduled_tick` when they start. An external scheduler may also wake a non-interactive harness and submit the same signal.
-
-OpenMerit calls `scheduleWakeup` only when the confirmed policy requests persistent execution, the adapter declares persistent scheduling and background execution, and any infrastructure-changing provisioning has been authorized. Paid agents, system scheduler installation, and cloud infrastructure remain harness implementation details and authorization boundaries.
-
-## Intent mapping
-
-OpenMerit owns deterministic mapping from due conditions to intents:
-
-| Due condition | Intent |
-| --- | --- |
-| Baseline cadence | Core checks stored baseline-window sufficiency; if ready, `discover_candidates` |
-| Mature frontier cadence or changed catalogue | `discover_candidates` |
-| Regression cadence or crossed metric threshold | `investigate_regression` |
-| Completed post-swap window | `verify_model_swap` |
-
-Subsequent lifecycle transitions continue through candidate trials, frontier calculation, supervised swap, verification, or rollback. The harness executes those intents; OpenMerit validates their structured result and evidence.
-
-## Pi behavior
-
-Pi reports catalogue and scheduled-tick signals on session start. Application instrumentation submits product-task, metric-window, and post-swap verification signals through its typed `openmerit_report_signal` tool; Pi's own settled-turn telemetry is not treated as product evidence.
-
-On macOS, a confirmed policy with `execution.mode: "persistent"` and `infrastructureChangesAllowed: true` allows the Pi adapter to install a per-project user LaunchAgent. It uses the model selected in the interactive Pi session and checks that Pi authentication works without shell-only credentials. The agent checks local state every five minutes without calling a model. When a baseline check is due, the runner submits `scheduled_tick` directly to core: an insufficient result exits without starting Pi; a sufficient result starts Pi for candidate discovery. The Mac must be logged in; this is not a cloud service, an exact-time alarm, or a source of product metrics. Task-count and metric-window checks still depend on application signals.
-
-Background candidate work remains experimental. A local runner test verifies that an insufficient baseline check needs no Pi process. Candidate discovery, comparison, and swapping from a background Pi run are not yet product-validated. A background Pi run is capped at 15 minutes and writes its exit code and any still-active intent ID to `.openmerit/scheduler-status.json`; an unfinished intent requires inspection and explicit recovery in Pi.
-
-`/openmerit pause` persists the pause, unloads the project's LaunchAgent, and prevents automatic due decisions while still recording incoming signals. `/openmerit resume` clears the pause and restores an authorized schedule. Neither command cancels already-active work. A declined or failed scheduler installation is reported as a gap, not success. On other platforms, persistent policies still require an external scheduler.