harness-everything 0.20.7 → 0.22.0

package/plugins/harness-everything/skills/harness-everything/scripts/system-one/cua_adapter.py

@@ -0,0 +1,353 @@
+"""Optional CPU CUA-S1 bridge. Stdout is protocol-only; never execute UI actions."""
+import hashlib
+import hmac
+import json
+import os
+from pathlib import Path
+import re
+import secrets
+import socket
+import subprocess
+import sys
+import threading
+import time
+
+
+def verify_artifacts(manifest):
+    weights = Path(manifest['checkpoint'])
+    if not weights.is_absolute() or weights.suffix != '.safetensors':
+        raise ValueError('checkpoint-format')
+    for file, key in [(weights, 'weightsSha256'), (weights.with_suffix('.json'), 'configSha256')]:
+        with file.open('rb') as handle:
+            digest = hashlib.file_digest(handle, 'sha256').hexdigest()
+        if digest != manifest[key]:
+            raise ValueError('artifact-hash')
+    return weights
+
+
+def check_limits(request, config):
+    if len(request['context'].encode('utf-8')) > config['context_tokens'] or any(
+        len(option['text'].encode('utf-8')) > config['option_tokens'] for option in request['options']
+    ):
+        raise ValueError('input-too-long')
+
+
+def load_scorer(weights, manifest):
+    """Load the verified checkpoint once; return (score(request) -> probabilities, config)."""
+    import torch
+    from cua_s1.model import ChoiceExample, load_checkpoint
+
+    torch.set_num_threads(1)
+    torch.use_deterministic_algorithms(True)
+    model, collator, config = load_checkpoint(weights, 'cpu')
+
+    def score(request):
+        example = ChoiceExample(context=request['context'], options=tuple(o['text'] for o in request['options']), label=0)
+        with torch.inference_mode():
+            return model(collator([example])).softmax(-1)[0].tolist()
+    return score, config
+
+
+def build_response(request, manifest, probabilities):
+    return {
+        'schemaVersion': 1, 'requestHash': request['requestHash'], 'catalogHash': request['catalogHash'],
+        'model': {'id': manifest['modelId'], 'revision': manifest['revision'], 'domain': manifest['domain']},
+        'scores': [{'id': option['id'], 'probability': probability} for option, probability in zip(request['options'], probabilities, strict=True)],
+    }
+
+
+def infer(request, manifest):
+    weights = verify_artifacts(manifest)
+    score, config = load_scorer(weights, manifest)
+    check_limits(request, config)
+    return build_response(request, manifest, score(request))
+
+
+MAX_REQUEST_BYTES = 2 * 1024 * 1024
+MAX_OPTIONS = 256
+MAX_CLIENTS = 64
+READ_DEADLINE_S = 1.0  # never longer than the Node client's 1000 ms call deadline
+STARTUP_REASONS = ('artifact-hash', 'checkpoint-format')
+ID_PATTERN = re.compile(r'[a-z0-9._-]{1,80}')
+HASH_PATTERN = re.compile(r'[0-9a-f]{64}')
+_USER_SID = []
+
+
+def _artifact_stamp(weights):
+    return [(p.stat().st_size, p.stat().st_mtime_ns) for p in (weights, weights.with_suffix('.json'))]
+
+
+def _restrict_to_current_user(path):
+    """Windows: replace the whole DACL with one protected full-control ACE for the current user.
+
+    Editing ACEs is not enough: some hosts create files with explicit (non-inherited) SYSTEM,
+    Administrators or OWNER RIGHTS entries that survive `icacls /inheritance:r /grant:r`.
+    """
+    if os.name != 'nt':
+        return
+    import ctypes
+    from ctypes import wintypes
+    if not _USER_SID:
+        tools = Path(os.environ.get('SystemRoot', 'C:/Windows')) / 'System32'
+        out = subprocess.run([str(tools / 'whoami.exe'), '/user', '/fo', 'csv', '/nh'],
+                             capture_output=True, text=True, timeout=10, check=True).stdout
+        sid = out.strip().split(',')[-1].strip().strip('"')
+        if not re.fullmatch(r'S-1-[0-9-]+', sid):
+            raise OSError('user-sid')
+        _USER_SID.append(sid)
+    advapi32 = ctypes.WinDLL('advapi32', use_last_error=True)
+    kernel32 = ctypes.WinDLL('kernel32', use_last_error=True)
+    descriptor = ctypes.c_void_p()
+    if not advapi32.ConvertStringSecurityDescriptorToSecurityDescriptorW(
+            f'D:P(A;;FA;;;{_USER_SID[0]})', 1, ctypes.byref(descriptor), None):
+        raise OSError('dacl-build')
+    try:
+        present, defaulted, dacl = wintypes.BOOL(), wintypes.BOOL(), ctypes.c_void_p()
+        if not advapi32.GetSecurityDescriptorDacl(descriptor, ctypes.byref(present), ctypes.byref(dacl), ctypes.byref(defaulted)):
+            raise OSError('dacl-read')
+        SE_FILE_OBJECT, DACL_INFO, PROTECTED_DACL_INFO = 1, 0x4, 0x80000000
+        advapi32.SetNamedSecurityInfoW.argtypes = [wintypes.LPWSTR, ctypes.c_int, wintypes.DWORD,
+                                                   ctypes.c_void_p, ctypes.c_void_p, ctypes.c_void_p, ctypes.c_void_p]
+        if advapi32.SetNamedSecurityInfoW(str(path), SE_FILE_OBJECT, DACL_INFO | PROTECTED_DACL_INFO, None, None, dacl, None) != 0:
+            raise OSError('dacl-set')
+    finally:
+        kernel32.LocalFree(descriptor)
+
+
+def _write_private_json(target, value):
+    """Atomic replace of an owner-only file (0600; explicit owner-only DACL on Windows) before the token is written."""
+    tmp = target.with_name(f'.{target.name}.{os.getpid()}.{secrets.token_hex(4)}.tmp')
+    os.close(os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600))
+    _restrict_to_current_user(tmp)
+    with open(tmp, 'w', encoding='utf-8') as handle:
+        json.dump(value, handle)
+    os.replace(tmp, target)
+
+
+def _read_request_line(conn):
+    buffer = bytearray()
+    while b'\n' not in buffer and len(buffer) <= MAX_REQUEST_BYTES:
+        chunk = conn.recv(65536)
+        if not chunk:
+            break
+        buffer.extend(chunk)
+    if len(buffer.split(b'\n', 1)[0]) > MAX_REQUEST_BYTES:
+        # Drain to EOF (bounded by size and the read deadline) so the reply is not lost to a reset.
+        drained = 0
+        try:
+            while drained < 8 * MAX_REQUEST_BYTES and conn.recv(65536):
+                drained += 65536
+        except OSError:
+            pass
+        raise ValueError('request-limit')
+    return bytes(buffer).split(b'\n', 1)[0]
+
+
+def _valid_score_request(request):
+    """Phase 0 request structure. Hashes are fingerprints, not authentication, so they are shape-checked only."""
+    if (not isinstance(request, dict)
+            or set(request) != {'schemaVersion', 'task', 'context', 'options', 'catalogHash', 'requestHash'}
+            or request['schemaVersion'] != 1 or not isinstance(request['task'], str) or not ID_PATTERN.fullmatch(request['task'])
+            or not isinstance(request['context'], str)
+            or not all(isinstance(request[k], str) and HASH_PATTERN.fullmatch(request[k]) for k in ('catalogHash', 'requestHash'))):
+        return False
+    options = request['options']
+    if not isinstance(options, list) or not 2 <= len(options) <= MAX_OPTIONS:
+        return False
+    if any(not isinstance(o, dict) or set(o) != {'id', 'text'} or not isinstance(o['id'], str)
+           or not ID_PATTERN.fullmatch(o['id']) or not isinstance(o['text'], str) for o in options):
+        return False
+    return len({o['id'] for o in options}) == len(options)
+
+
+def _handle(conn, token, manifest, weights, stamp, score, config):
+    """Return (reply, stop). Errors carry bounded reason codes only: no prompt, path, or traceback."""
+    invalid = {'ok': False, 'reason': 'invalid-request'}
+    try:
+        line = _read_request_line(conn)
+    except ValueError:
+        return {'ok': False, 'reason': 'request-limit'}, False
+    except OSError:
+        return invalid, False
+    try:
+        message = json.loads(line)
+    except ValueError:
+        return invalid, False
+    if not isinstance(message, dict):
+        return invalid, False
+    supplied = message.get('token')
+    if not isinstance(supplied, str) or not hmac.compare_digest(supplied.encode('utf-8'), token.encode('utf-8')):
+        return {'ok': False, 'reason': 'unauthorized'}, False
+    op = message.get('op')
+    if op == 'ping':
+        return {'ok': True, 'pid': os.getpid(), 'model': {'id': manifest['modelId'], 'revision': manifest['revision'], 'domain': manifest['domain']}}, False
+    if op == 'shutdown':
+        return {'ok': True}, True
+    if op != 'score' or not _valid_score_request(message.get('request')):
+        return invalid, False
+    try:
+        changed = _artifact_stamp(weights) != stamp
+    except OSError:
+        changed = True
+    if changed:
+        return {'ok': False, 'reason': 'artifact-changed'}, True
+    request = message['request']
+    try:
+        check_limits(request, config)
+    except ValueError:
+        return {'ok': False, 'reason': 'input-too-long'}, False
+    try:
+        return {'ok': True, 'response': build_response(request, manifest, score(request))}, False
+    except Exception:
+        return {'ok': False, 'reason': 'score-failed'}, False
+
+
+def serve(manifest, state_path, lock_path, scorer_factory=None, idle_timeout_s=None):
+    """Resident loopback scorer: verify, load once, publish state, serve until idle/shutdown/artifact change."""
+    state_path, lock_path = Path(state_path), Path(lock_path)
+    try:
+        weights = verify_artifacts(manifest)
+        stamp = _artifact_stamp(weights)
+        score, config = (scorer_factory or load_scorer)(weights, manifest)
+    except Exception as exc:
+        reason = str(exc) if str(exc) in STARTUP_REASONS else 'load-failed'
+        try:
+            _write_private_json(lock_path, {'failed': reason, 'at': time.time()})
+        except OSError:
+            pass
+        return 1
+    idle = idle_timeout_s if idle_timeout_s is not None else manifest.get('idleTimeoutMs', 1800000) / 1000
+    token = secrets.token_hex(32)
+    pid = os.getpid()
+    stop = threading.Event()
+    score_lock = threading.Lock()  # one model, one inference at a time; connections are handled concurrently
+    slots = threading.BoundedSemaphore(MAX_CLIENTS)
+
+    def guarded_score(request):
+        with score_lock:
+            return score(request)
+
+    def send(conn, reply):
+        try:
+            conn.sendall((json.dumps(reply, allow_nan=False) + '\n').encode('utf-8'))
+        except OSError:
+            pass
+
+    def worker(conn):
+        try:
+            with conn:
+                conn.settimeout(READ_DEADLINE_S)
+                reply, halt = _handle(conn, token, manifest, weights, stamp, guarded_score, config)
+                send(conn, reply)
+            if halt:
+                stop.set()
+        finally:
+            slots.release()
+
+    server = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    try:
+        server.bind(('127.0.0.1', 0))
+        server.listen(MAX_CLIENTS)
+        server.settimeout(0.25)
+        _write_private_json(state_path, {'schemaVersion': 1, 'pid': pid, 'port': server.getsockname()[1], 'token': token, 'startedAt': time.time()})
+        try:
+            lock_path.unlink()
+        except FileNotFoundError:
+            pass
+        last = time.monotonic()
+        # A server whose state file no longer names it is undiscoverable (replaced or corrupted): exit, never orphan.
+        while not stop.is_set() and time.monotonic() - last <= idle and _owns_state(state_path, pid, token):
+            try:
+                conn, _ = server.accept()
+            except socket.timeout:
+                continue
+            last = time.monotonic()
+            if not slots.acquire(blocking=False):
+                with conn:
+                    conn.settimeout(0.2)
+                    try:
+                        _read_request_line(conn)
+                    except (OSError, ValueError):
+                        pass
+                    send(conn, {'ok': False, 'reason': 'busy'})
+                continue
+            threading.Thread(target=worker, args=(conn,), daemon=True).start()
+    finally:
+        server.close()
+        if _owns_state(state_path, pid, token, missing=False):
+            try:
+                state_path.unlink()
+            except OSError:
+                pass
+    return 0
+
+
+def _owns_state(state_path, pid, token, missing=False):
+    """True while the state file still names this server. A transient Windows sharing violation counts as owned."""
+    try:
+        data = json.loads(state_path.read_text(encoding='utf-8'))
+    except FileNotFoundError:
+        return missing
+    except OSError:
+        return True
+    except ValueError:
+        return False
+    return isinstance(data, dict) and data.get('pid') == pid and data.get('token') == token
+
+
+def serve_main(argv, scorer_factory=None):
+    if len(argv) != 3:
+        return 2
+    return serve(json.loads(argv[0]), argv[1], argv[2], scorer_factory=scorer_factory)
+
+
+def source_revision(direct_url_text):
+    """Return the PEP 610 VCS commit recorded at install time, or None when unprovable."""
+    try:
+        commit = json.loads(direct_url_text)['vcs_info']['commit_id']
+    except Exception:
+        return None
+    return commit if isinstance(commit, str) and re.fullmatch(r'[0-9a-f]{40}', commit) else None
+
+
+def provenance():
+    """Installed runtime/source facts only; never imports torch or loads a checkpoint."""
+    import importlib.metadata as metadata
+    import platform
+
+    cua = {'distribution': None, 'version': None, 'sourceRevision': None}
+    names = sorted(set(metadata.packages_distributions().get('cua_s1', [])))
+    if len(names) == 1:
+        dist = metadata.distribution(names[0])
+        cua = {'distribution': names[0], 'version': dist.version, 'sourceRevision': source_revision(dist.read_text('direct_url.json'))}
+    try:
+        torch = metadata.version('torch')
+    except metadata.PackageNotFoundError:
+        torch = None
+    return {'schemaVersion': 1, 'python': {'implementation': platform.python_implementation(), 'version': platform.python_version()},
+            'cuaS1': cua, 'torch': torch}
+
+
+def main():
+    try:
+        if sys.argv[1:] == ['--provenance']:
+            print(json.dumps(provenance(), allow_nan=False))
+            return 0
+        if sys.argv[1:2] == ['--serve']:
+            return serve_main(sys.argv[2:])
+        manifest = json.loads(sys.argv[1])
+        raw = sys.stdin.buffer.read(2 * 1024 * 1024 + 1)
+        if len(raw) > 2 * 1024 * 1024:
+            raise ValueError('request-limit')
+        request = json.loads(raw)
+        result = infer(request, manifest)
+        print(json.dumps(result, allow_nan=False))
+    except Exception:
+        # No raw prompt, selected values, artifact paths, or traceback on the wire.
+        print('cua-provider-unavailable', file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())

package/plugins/harness-everything/skills/harness-everything/scripts/system-one/evaluate.js

@@ -0,0 +1,98 @@
+'use strict';
+const { validateRequest } = require('./contract');
+const { TIER_OPTIONS } = require('./router');
+const exact = (obj, keys) => obj && typeof obj === 'object' && !Array.isArray(obj) && Object.keys(obj).length === keys.length && keys.every(k => Object.hasOwn(obj, k));
+const nonempty = v => typeof v === 'string' && v.trim().length > 0;
+const labels = ['tier1', 'tier2', 'tier3', null];
+const finite = v => typeof v === 'number' && Number.isFinite(v);
+const fail = () => { throw new TypeError('invalid-evaluation-input'); };
+function validateCorpus(corpus) {
+  if (!exact(corpus, ['schemaVersion', 'cases']) || corpus.schemaVersion !== 1 || !Array.isArray(corpus.cases) || !corpus.cases.length) fail();
+  const ids = new Set(); const hashes = new Set(); const families = new Map();
+  for (const c of corpus.cases) {
+    if (!exact(c, ['id', 'family', 'split', 'language', 'source', 'reviewed', 'request', 'gold'])
+      || ![c.id, c.family, c.source].every(nonempty) || !['train', 'validation', 'holdout'].includes(c.split)
+      || !['en', 'zh-TW'].includes(c.language) || typeof c.reviewed !== 'boolean' || !labels.includes(c.gold)) fail();
+    validateRequest(c.request);
+    if (c.request.task !== 'tier' || JSON.stringify(c.request.options) !== JSON.stringify(TIER_OPTIONS)
+      || ids.has(c.id) || hashes.has(c.request.requestHash) || (families.has(c.family) && families.get(c.family) !== c.split)) fail();
+    ids.add(c.id); hashes.add(c.request.requestHash); families.set(c.family, c.split);
+  }
+  return true;
+}
+function prediction(decision) {
+  if (exact(decision, ['status', 'reason']) && decision.status === 'unavailable' && nonempty(decision.reason)) return null;
+  if (!exact(decision, ['status', 'reason', 'selectedId', 'confidence', 'margin', 'model'])
+    || !['accepted', 'abstain', 'invalid-output'].includes(decision.status) || !nonempty(decision.reason)
+    || !labels.includes(decision.selectedId) || (decision.status === 'accepted') !== (decision.selectedId !== null)) fail();
+  for (const key of ['confidence', 'margin']) if (decision[key] !== null && (!finite(decision[key]) || decision[key] < 0 || decision[key] > 1)) fail();
+  if (decision.model !== null && (!exact(decision.model, ['id', 'revision', 'domain']) || !Object.values(decision.model).every(nonempty))) fail();
+  if (decision.status === 'accepted' && (decision.confidence === null || decision.margin === null || decision.model?.domain !== 'harness-routing-v1')) fail();
+  return decision.selectedId;
+}
+// Scored decisions carry the full catalog-order probability vector; unavailable/invalid outputs carry null.
+function checkScores(decision, scores) {
+  const scored = ['accepted', 'abstain'].includes(decision.status);
+  if (!scored) { if (scores !== null) fail(); return; }
+  if (!Array.isArray(scores) || scores.length !== TIER_OPTIONS.length
+    || scores.some(p => !finite(p) || p < 0 || p > 1) || Math.abs(scores.reduce((s, p) => s + p, 0) - 1) > 1e-6) fail();
+  const ranked = [...scores].sort((a, b) => b - a);
+  if (decision.confidence !== ranked[0] || decision.margin !== ranked[0] - ranked[1]) fail();
+}
+function metrics(gold, predicted) {
+  const count = gold.length;
+  const accepted = predicted.filter(x => x !== null).length;
+  const correct = predicted.filter((x, i) => x === gold[i]).length;
+  const acceptedCorrect = predicted.filter((x, i) => x !== null && x === gold[i]).length;
+  const macroF1 = labels.reduce((sum, label) => {
+    const tp = gold.filter((g, i) => g === label && predicted[i] === label).length;
+    const fp = gold.filter((g, i) => g !== label && predicted[i] === label).length;
+    const fn = gold.filter((g, i) => g === label && predicted[i] !== label).length;
+    return sum + (2 * tp + fp + fn ? 2 * tp / (2 * tp + fp + fn) : 0);
+  }, 0) / labels.length;
+  return { accuracy: correct / count, macroF1, coverage: accepted / count, abstentionRate: 1 - accepted / count,
+    acceptedPrecision: accepted ? acceptedCorrect / accepted : null,
+    acceptedErrorRate: accepted ? (accepted - acceptedCorrect) / accepted : null };
+}
+function p95(values) { return values.length ? [...values].sort((a, b) => a - b)[Math.ceil(values.length * 0.95) - 1] : null; }
+// sourceEvidence is the provider provenance result; only the pinned cua_s1 revision satisfies the gate.
+function evaluate(corpus, records, sourceEvidence = null) {
+  validateCorpus(corpus);
+  const cases = corpus.cases.filter(c => c.split === 'holdout');
+  if (!cases.length || !Array.isArray(records) || records.length !== cases.length) fail();
+  const byId = new Map(); const models = new Set(); const cold = []; const warm = [];
+  for (const record of records) {
+    if (!exact(record, ['id', 'baseline', 'runs']) || byId.has(record.id) || !cases.some(c => c.id === record.id)
+      || !labels.includes(record.baseline) || !Array.isArray(record.runs) || record.runs.length !== 2) fail();
+    for (const run of record.runs) {
+      if (!exact(run, ['decision', 'scores', 'latencyMs', 'coldStart']) || !finite(run.latencyMs) || run.latencyMs < 0 || typeof run.coldStart !== 'boolean') fail();
+      prediction(run.decision);
+      checkScores(run.decision, run.scores);
+      if (run.decision.model) models.add(JSON.stringify([run.decision.model.id, run.decision.model.revision, run.decision.model.domain]));
+      (run.coldStart ? cold : warm).push(run.latencyMs);
+    }
+    byId.set(record.id, record);
+  }
+  if (models.size > 1) fail();
+  const gold = cases.map(c => c.gold);
+  const baseline = metrics(gold, cases.map(c => byId.get(c.id).baseline));
+  const model = metrics(gold, cases.map(c => prediction(byId.get(c.id).runs[0].decision)));
+  const canonicalRun = ({ decision: d, scores }) => JSON.stringify([d.status, d.reason, d.selectedId ?? null, d.confidence ?? null, d.margin ?? null,
+    d.model ? [d.model.id, d.model.revision, d.model.domain] : null, scores]);
+  const agreement = records.filter(r => canonicalRun(r.runs[0]) === canonicalRun(r.runs[1])).length / cases.length;
+  const latency = { coldP95Ms: p95(cold), warmP95Ms: p95(warm), coldSamples: cold.length, warmSamples: warm.length };
+  const gates = {
+    reviewedHoldout: cases.length >= 200 && cases.every(c => c.reviewed)
+      && ['en', 'zh-TW'].every(lang => cases.filter(c => c.language === lang).length >= 50),
+    acceptedPrecision: model.acceptedPrecision !== null && model.acceptedPrecision >= 0.98,
+    coverage: model.coverage >= 0.8,
+    macroF1: model.macroF1 >= baseline.macroF1,
+    repeatability: agreement === 1,
+    warmLatency: warm.length >= cases.length && latency.warmP95Ms <= 100,
+    sourceProvenance: sourceEvidence?.status === 'recorded' && sourceEvidence.provenance?.cuaS1?.sourceRevisionStatus === 'pinned',
+    policyEvidence: false,
+    liveHostEvidence: false,
+  };
+  return { schemaVersion: 1, cases: cases.length, baseline, model, agreement, latency, gates, rolloutReady: Object.values(gates).every(Boolean) };
+}
+module.exports = { validateCorpus, evaluate };

package/plugins/harness-everything/skills/harness-everything/scripts/system-one/install.js

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+'use strict';
+// Opt-in System One installer: a dedicated venv, pinned cua_s1 source, and a pinned CPU checkpoint.
+// It is never run from hooks, and it never changes the router mode; it prints the environment to set.
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { createHash } = require('node:crypto');
+const { spawnSync } = require('node:child_process');
+const { performance } = require('node:perf_hooks');
+const { validateManifest, readManifest, provenance, score, PINNED_CUA_S1_REVISION } = require('./provider');
+const resident = require('./resident');
+const { createRequest, decide } = require('./contract');
+const { TIER_OPTIONS } = require('./router');
+
+const PINS = Object.freeze({
+  cuaS1Revision: PINNED_CUA_S1_REVISION,
+  cuaS1Spec: `cua-s1 @ git+https://github.com/trycua/cua@${PINNED_CUA_S1_REVISION}#subdirectory=libs/cua-s1/python`,
+  torchSpec: 'torch>=2.2,<3',
+  torchIndex: 'https://download.pytorch.org/whl/cpu',
+  modelId: 'cua-ai/cua-s1-forms',
+  modelRevision: 'f54adbf447f4ca6ec259f529ee3f2e3e09f8cc71',
+  domain: 'forms-v1',
+  // sha256/size from the Hugging Face tree API at modelRevision (LFS oid for weights; the JSON
+  // sidecar's git blob id d8f8426a... was re-hashed to confirm these exact CRLF bytes).
+  files: Object.freeze({
+    weights: Object.freeze({ name: 'cua-s1-forms.safetensors', size: 2828784, sha256: '05954c1caf51c2fb6c13ea4acbfc88a2e7653dea192252bb51dc89e76a356ddc' }),
+    config: Object.freeze({ name: 'cua-s1-forms.json', size: 1053, sha256: '62d31e2f9a001a8e9b6f8534c5194d07ebdd3f9d62ef1ac281906622992650ca' }),
+  }),
+});
+const USAGE = 'Usage: install.js [--dir <absolute dir>] [--python <3.11-3.13 executable>] [--dry-run]';
+
+const defaultDir = () => path.join(os.homedir(), '.agents', 'harness-everything', 'system-one');
+const fileUrl = name => `https://huggingface.co/${PINS.modelId}/resolve/${PINS.modelRevision}/${name}`;
+const checkpointDir = dir => path.join(dir, 'checkpoints', PINS.modelRevision);
+const venvPython = (dir, platform = process.platform) => (platform === 'win32'
+  ? path.join(dir, 'venv', 'Scripts', 'python.exe') : path.join(dir, 'venv', 'bin', 'python'));
+function supportedPython(version) {
+  const match = typeof version === 'string' && /^3\.(\d+)\.\d+$/.exec(version);
+  return Boolean(match) && Number(match[1]) >= 11 && Number(match[1]) <= 13;
+}
+function pythonCandidates(platform = process.platform) {
+  return platform === 'win32'
+    ? [['py', '-3.13'], ['py', '-3.12'], ['py', '-3.11'], ['python'], ['python3']]
+    : [['python3.13'], ['python3.12'], ['python3.11'], ['python3'], ['python']];
+}
+function parseArgs(argv) {
+  const opts = { dir: defaultDir(), python: null, dryRun: false };
+  const seen = new Set();
+  for (let i = 0; i < argv.length; i++) {
+    const flag = argv[i];
+    if (seen.has(flag)) throw new Error('usage');
+    seen.add(flag);
+    if (flag === '--dry-run') opts.dryRun = true;
+    else if (flag === '--dir' || flag === '--python') {
+      const value = argv[++i];
+      if (!value || value.startsWith('--')) throw new Error('usage');
+      if (flag === '--dir' && !path.isAbsolute(value)) throw new Error('usage');
+      opts[flag.slice(2)] = flag === '--dir' ? path.resolve(value) : value;
+    } else throw new Error('usage');
+  }
+  return opts;
+}
+function buildManifest(dir, python) {
+  const manifest = { schemaVersion: 1, python, checkpoint: path.join(checkpointDir(dir), PINS.files.weights.name),
+    weightsSha256: PINS.files.weights.sha256, configSha256: PINS.files.config.sha256,
+    modelId: PINS.modelId, revision: PINS.modelRevision, domain: PINS.domain,
+    // One-shot fallback budget (fresh Python + torch import per call); resident keeps the model loaded.
+    timeoutMs: 10000, transport: 'resident', idleTimeoutMs: 1800000 };
+  validateManifest(manifest);
+  return manifest;
+}
+const matches = (buf, spec) => buf.length === spec.size && createHash('sha256').update(buf).digest('hex') === spec.sha256;
+async function httpFetch(url) {
+  const res = await fetch(url, { redirect: 'follow' });
+  if (!res.ok) throw new Error(`download-failed:${res.status}`);
+  return Buffer.from(await res.arrayBuffer());
+}
+async function ensureFile(url, dest, spec, fetcher = httpFetch) {
+  if (fs.existsSync(dest) && matches(fs.readFileSync(dest), spec)) return 'verified-existing';
+  const bytes = await fetcher(url);
+  if (!Buffer.isBuffer(bytes) || !matches(bytes, spec)) throw new Error(`download-verification:${spec.name}`);
+  const tmp = `${dest}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, bytes);
+  fs.renameSync(tmp, dest);
+  return 'downloaded';
+}
+function exec(cmd, args, capture = false) {
+  // Child progress goes to stderr (fd 2): stdout carries only the final JSON report.
+  const result = spawnSync(cmd, args, { shell: false, windowsHide: true, encoding: 'utf8', stdio: capture ? 'pipe' : ['ignore', 2, 2] });
+  if (result.error || result.status !== 0) throw new Error(`command-failed: ${[cmd, ...args].join(' ')}`);
+  return capture ? result.stdout.trim() : '';
+}
+const VERSION_PROBE = ['-c', 'import sys; print("%d.%d.%d" % sys.version_info[:3])'];
+function findPython(explicit) {
+  for (const [cmd, ...pre] of explicit ? [[explicit]] : pythonCandidates()) {
+    const result = spawnSync(cmd, [...pre, ...VERSION_PROBE], { shell: false, windowsHide: true, encoding: 'utf8' });
+    const version = result.status === 0 ? result.stdout.trim() : null;
+    if (supportedPython(version)) return { cmd, pre, version };
+  }
+  throw new Error(explicit ? 'python-unsupported: need Python 3.11-3.13' : 'python-not-found: install Python 3.11-3.13 or pass --python');
+}
+function plan(opts) {
+  const venvPy = venvPython(opts.dir);
+  const manifestPath = path.join(opts.dir, 'manifest.json');
+  return { dir: opts.dir, manifest: manifestPath,
+    steps: [
+      `create venv ${path.join(opts.dir, 'venv')} with ${opts.python || 'first Python 3.11-3.13 found'}`,
+      `${venvPy} -m pip install --index-url ${PINS.torchIndex} "${PINS.torchSpec}"`,
+      `${venvPy} -m pip install "${PINS.cuaS1Spec}"`,
+      ...Object.values(PINS.files).map(f => `download ${fileUrl(f.name)} (sha256 ${f.sha256})`),
+      `write ${manifestPath}`,
+      'verify provenance (pinned revision), start the resident server, one warm CPU inference, stop it',
+    ],
+    env: { HARNESS_SYSTEM_ONE_MODE: 'shadow', HARNESS_SYSTEM_ONE_CONFIG: manifestPath } };
+}
+// Starts the resident server (if needed), scores once warm, then stops a server it started.
+function verify(manifestPath) {
+  const source = provenance(manifestPath);
+  const manifest = readManifest(manifestPath);
+  const wasRunning = resident.status(manifest, manifestPath).running;
+  const startMs = performance.now();
+  const ready = resident.ensureReady(manifest, manifestPath, 60000);
+  const readyMs = Math.round(performance.now() - startMs);
+  const request = createRequest('tier', 'fix a typo in README', TIER_OPTIONS);
+  const start = performance.now();
+  const result = score(request, manifestPath);
+  const latencyMs = Math.round(performance.now() - start);
+  if (!wasRunning) resident.stop(manifest, manifestPath);
+  const decision = result.status === 'scored' ? decide(request, result.response) : result;
+  const scores = result.status === 'scored' && decision.status !== 'invalid-output' ? result.response.scores : null;
+  const ok = ready && source.status === 'recorded' && source.provenance.cuaS1.sourceRevisionStatus === 'pinned' && scores !== null;
+  return { ok, source, residentReady: ready, readyMs, decision, scores, latencyMs };
+}
+async function main(argv) {
+  const opts = parseArgs(argv);
+  const p = plan(opts);
+  if (opts.dryRun) { process.stdout.write(`${JSON.stringify({ dryRun: true, ...p }, null, 2)}\n`); return 0; }
+  const base = findPython(opts.python);
+  const venvPy = venvPython(opts.dir);
+  fs.mkdirSync(checkpointDir(opts.dir), { recursive: true });
+  if (!fs.existsSync(venvPy)) exec(base.cmd, [...base.pre, '-m', 'venv', path.join(opts.dir, 'venv')]);
+  const venvVersion = exec(venvPy, VERSION_PROBE, true);
+  if (!supportedPython(venvVersion)) throw new Error(`python-unsupported: existing venv uses ${venvVersion}`);
+  exec(venvPy, ['-m', 'pip', 'install', '--disable-pip-version-check', '--index-url', PINS.torchIndex, PINS.torchSpec]);
+  exec(venvPy, ['-m', 'pip', 'install', '--disable-pip-version-check', PINS.cuaS1Spec]);
+  for (const spec of Object.values(PINS.files)) {
+    console.error(`${spec.name}: ${await ensureFile(fileUrl(spec.name), path.join(checkpointDir(opts.dir), spec.name), spec)}`);
+  }
+  fs.writeFileSync(p.manifest, `${JSON.stringify(buildManifest(opts.dir, venvPy), null, 2)}\n`);
+  const check = verify(p.manifest);
+  process.stdout.write(`${JSON.stringify({ dryRun: false, ...p, verification: check }, null, 2)}\n`);
+  return check.ok ? 0 : 1;
+}
+if (require.main === module) {
+  main(process.argv.slice(2)).then(code => { process.exitCode = code; }, err => {
+    if (err.message === 'usage') { console.error(USAGE); process.exitCode = 2; return; }
+    console.error(`System One install failed: ${err.message}`); process.exitCode = 1;
+  });
+}
+module.exports = { PINS, fileUrl, venvPython, supportedPython, pythonCandidates, parseArgs, buildManifest, ensureFile, exec, plan, verify };