codna 0.1.0__tar.gz

codna-0.1.0/MANIFEST.in

@@ -0,0 +1,6 @@
+exclude codna/_telys_runtime/libame_kernel.*
+exclude codna/_telys_runtime/manifest.json
+recursive-exclude codna/_telys_runtime libame_kernel.* manifest.json
+recursive-exclude .codna *
+recursive-exclude .codna-memory *
+global-exclude keys.txt .keys.txt .env .env.* *.log *.pem *.key *.jwt local-stack.json launcher.state

codna-0.1.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: codna
+Version: 0.1.0
+Summary: Local-first repo intelligence and agent fixing for Codna.
+Author: Thyn
+Maintainer: Thyn
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://codna.ai
+Project-URL: Documentation, https://docs.codna.ai
+Project-URL: Source, https://github.com/thyn-ai/codna
+Project-URL: Issues, https://github.com/thyn-ai/codna/issues
+Project-URL: Security, https://codna.ai/security
+Keywords: agent,ai,code-intelligence,codna,debugging,mcp,repository-intelligence,telys
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Bug Tracking
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: pyarrow>=15.0.0
+Provides-Extra: mcp
+Provides-Extra: memory
+Requires-Dist: telys>=0.1.0b1; extra == "memory"
+Requires-Dist: telys-runtime>=0.1.0a1; extra == "memory"
+Requires-Dist: numpy>=1.24; extra == "memory"
+Requires-Dist: faiss-cpu>=1.7; extra == "memory"
+Requires-Dist: wordllama>=0.3; extra == "memory"
+Requires-Dist: tree-sitter>=0.23; extra == "memory"
+Requires-Dist: tree-sitter-javascript; extra == "memory"
+Requires-Dist: tree-sitter-typescript; extra == "memory"
+Requires-Dist: tree-sitter-go; extra == "memory"
+Requires-Dist: tree-sitter-rust; extra == "memory"
+Requires-Dist: tree-sitter-java; extra == "memory"
+Requires-Dist: tree-sitter-c; extra == "memory"
+Requires-Dist: tree-sitter-cpp; extra == "memory"
+Requires-Dist: tree-sitter-c-sharp; extra == "memory"
+Requires-Dist: tree-sitter-php; extra == "memory"
+Requires-Dist: tree-sitter-ruby; extra == "memory"
+Provides-Extra: memory-algenta
+Requires-Dist: telys>=0.1.0b1; extra == "memory-algenta"
+Requires-Dist: telys-runtime>=0.1.0a1; extra == "memory-algenta"
+Requires-Dist: numpy>=1.24; extra == "memory-algenta"
+Requires-Dist: faiss-cpu>=1.7; extra == "memory-algenta"
+Requires-Dist: telys-algenta[algenta]>=0.1.0a1; extra == "memory-algenta"
+Provides-Extra: memory-rerank
+Requires-Dist: wordllama>=0.3; extra == "memory-rerank"
+Provides-Extra: memory-languages
+Requires-Dist: tree-sitter>=0.23; extra == "memory-languages"
+Requires-Dist: tree-sitter-javascript; extra == "memory-languages"
+Requires-Dist: tree-sitter-typescript; extra == "memory-languages"
+Requires-Dist: tree-sitter-go; extra == "memory-languages"
+Requires-Dist: tree-sitter-rust; extra == "memory-languages"
+Requires-Dist: tree-sitter-java; extra == "memory-languages"
+Requires-Dist: tree-sitter-c; extra == "memory-languages"
+Requires-Dist: tree-sitter-cpp; extra == "memory-languages"
+Requires-Dist: tree-sitter-c-sharp; extra == "memory-languages"
+Requires-Dist: tree-sitter-php; extra == "memory-languages"
+Requires-Dist: tree-sitter-ruby; extra == "memory-languages"
+
+# Codna CLI
+
+Codna is a local-first code intelligence and fixing CLI. It maps a repository,
+builds focused evidence for the agent, applies patches through the local Codna
+runtime, and reports verification evidence without requiring users to manage a
+separate local database or engine stack.
+
+## Install
+
+```bash
+pip install codna
+```
+
+Codna supports Python 3.10 and newer on macOS and Linux.
+
+## Common Commands
+
+```bash
+codna doctor
+codna doctor --start-stack
+codna triage .
+codna fix . --issue "describe the failing test or production bug"
+codna mcp
+```
+
+`codna doctor` is read-only by default. `codna doctor --start-stack` starts the
+owned local runtime when you explicitly ask for it. Normal fix and benchmark
+paths use the same runtime contract.
+
+## What Codna Runs Locally
+
+The base install includes the local Arrow/Parquet artifact dependency required
+for repository-intelligence step history. Clean installs include a packaged
+local repository backend for snapshot, triage, sidecar-backed fix planning,
+deterministic patch simulation, and explicit local-branch apply.
+
+Codna's normal local product path uses the local Algenta SDK/core in process for
+repository intelligence. No local Postgres is required. Local runtime state is
+kept under the user's Codna runtime directory, and the agent sidecar is started
+only when needed.
+
+## MCP
+
+Codna can run as a local MCP server for editors and agents that support MCP:
+
+```bash
+codna mcp
+```
+
+Use this when Cursor, Claude, or another MCP-compatible client needs Codna's
+repo understanding as a local tool.
+
+## Optional Local Memory
+
+Optional local code-memory support is available through:
+
+```bash
+pip install "codna[memory]"
+```
+
+The memory extra uses Telys for on-device retrieval. Release builds can include
+signed native Telys runtime artifacts for supported platforms. Source
+distributions intentionally exclude bundled native runtime artifacts.
+
+## Security And Local Files
+
+Codna is designed for local-first operation:
+
+- Secrets are never required in source control.
+- Local runtime state and logs stay on the user's machine.
+- Generated release artifacts are not included in source distributions.
+- Secrets, local runtime state, logs, `.env` files, key files, and bundled
+  native runtime artifacts are excluded from source distributions.
+
+## Links
+
+- Homepage: https://codna.ai
+- Documentation: https://docs.codna.ai
+- Source: https://github.com/thyn-ai/codna
+- Security: https://codna.ai/security

codna-0.1.0/README.md

@@ -0,0 +1,80 @@
+# Codna CLI
+
+Codna is a local-first code intelligence and fixing CLI. It maps a repository,
+builds focused evidence for the agent, applies patches through the local Codna
+runtime, and reports verification evidence without requiring users to manage a
+separate local database or engine stack.
+
+## Install
+
+```bash
+pip install codna
+```
+
+Codna supports Python 3.10 and newer on macOS and Linux.
+
+## Common Commands
+
+```bash
+codna doctor
+codna doctor --start-stack
+codna triage .
+codna fix . --issue "describe the failing test or production bug"
+codna mcp
+```
+
+`codna doctor` is read-only by default. `codna doctor --start-stack` starts the
+owned local runtime when you explicitly ask for it. Normal fix and benchmark
+paths use the same runtime contract.
+
+## What Codna Runs Locally
+
+The base install includes the local Arrow/Parquet artifact dependency required
+for repository-intelligence step history. Clean installs include a packaged
+local repository backend for snapshot, triage, sidecar-backed fix planning,
+deterministic patch simulation, and explicit local-branch apply.
+
+Codna's normal local product path uses the local Algenta SDK/core in process for
+repository intelligence. No local Postgres is required. Local runtime state is
+kept under the user's Codna runtime directory, and the agent sidecar is started
+only when needed.
+
+## MCP
+
+Codna can run as a local MCP server for editors and agents that support MCP:
+
+```bash
+codna mcp
+```
+
+Use this when Cursor, Claude, or another MCP-compatible client needs Codna's
+repo understanding as a local tool.
+
+## Optional Local Memory
+
+Optional local code-memory support is available through:
+
+```bash
+pip install "codna[memory]"
+```
+
+The memory extra uses Telys for on-device retrieval. Release builds can include
+signed native Telys runtime artifacts for supported platforms. Source
+distributions intentionally exclude bundled native runtime artifacts.
+
+## Security And Local Files
+
+Codna is designed for local-first operation:
+
+- Secrets are never required in source control.
+- Local runtime state and logs stay on the user's machine.
+- Generated release artifacts are not included in source distributions.
+- Secrets, local runtime state, logs, `.env` files, key files, and bundled
+  native runtime artifacts are excluded from source distributions.
+
+## Links
+
+- Homepage: https://codna.ai
+- Documentation: https://docs.codna.ai
+- Source: https://github.com/thyn-ai/codna
+- Security: https://codna.ai/security

codna-0.1.0/codna/__init__.py

@@ -0,0 +1,8 @@
+"""Codna — the agent that understands and fixes your repository.
+
+Codna is the user-facing product: the agent head + the Algenta engine behind it.
+This package is the `codna` CLI. Users never touch "algenta" directly — the engine
+is an internal dependency reached over HTTP.
+"""
+
+__version__ = "0.1.0"

codna-0.1.0/codna/_wheel_guard.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+MANIFEST_NAME = "manifest.json"
+KERNEL_GLOB = "libame_kernel.*"
+
+
+def package_runtime_dir() -> Path:
+    return Path(__file__).resolve().parent / "_telys_runtime"
+
+
+def staged_runtime_files(runtime_dir: Path) -> tuple[Path | None, tuple[Path, ...]]:
+    manifest = runtime_dir / MANIFEST_NAME
+    kernels = tuple(sorted(runtime_dir.glob(KERNEL_GLOB))) if runtime_dir.is_dir() else ()
+    return (manifest if manifest.exists() else None), kernels
+
+
+def requires_platform_wheel(runtime_dir: Path) -> bool:
+    manifest, kernels = staged_runtime_files(runtime_dir)
+    return manifest is not None or bool(kernels)
+
+
+def validate_wheel_filename(wheel_name: str, runtime_dir: Path) -> None:
+    if requires_platform_wheel(runtime_dir) and wheel_name.endswith("-py3-none-any.whl"):
+        raise ValueError(
+            "native Telys package-runtime artifacts require a platform-specific wheel tag"
+        )

codna-0.1.0/codna/admission_control.py

@@ -0,0 +1,275 @@
+"""MC-predictive admission control for parallel Codna fixes.
+
+A fix's wall-clock is dominated by the agent + model calls; running too many at once makes every
+in-flight fix share the model's throughput, so the slow tail blows past the SLA (the rust/clap
+>900s timeouts we measured). A static concurrency cap can't see that — it admits a fix that will
+miss the SLA, or it idles capacity that's actually free.
+
+This admitter governs concurrency *predictively*:
+
+  1. Deterministic floor: admit freely up to ``det_cap = min(ceiling, model_rate_budget)`` — clearly
+     safe, no prediction needed.
+  2. Hard ceiling: never exceed ``ceiling`` (the sidecar's AGENT_CORE_MAX_CONCURRENCY).
+  3. MC zone (between det_cap and ceiling): run a Monte-Carlo over the observed fix-duration
+     distribution under the contention the new fix would create, and admit only while
+     ``P(new fix breaches the SLA) < breach_threshold``.
+
+This is Algenta's own Monte-Carlo discipline applied to its own concurrency. The breach predictor is
+**pluggable** (``mc_fn``), with two strategies — both fully LOCAL, ZERO network round-trip:
+
+  • **mojo kernel (default)** — Algenta's compiled ``monte_carlo`` kernel makes the decision, reached
+    through the LOCAL SDK exactly like every fix step (``POST /v1/simulate`` → the loopback daemon, a
+    kernel memory copy on 127.0.0.1, no NIC, no egress). It fits a lognormal to the observed durations
+    (shifted by the contention factor) with objective ``sla - duration`` and reads back
+    ``metrics.probability_of_loss`` ( == P(duration > sla) ) — verified against the live kernel. This
+    is the "mojo decides, in real time" design: the same native engine that governs each fix also
+    governs how many fixes run at once. (The predictor only runs in the contended zone — det_cap < n ≤
+    ceiling; single / low concurrency is admitted at the deterministic floor outright.)
+  • **numpy in-process (fallback)** — an empirical bootstrap over the same observed durations, used
+    automatically if the kernel isn't reachable yet (daemon still warming up) and as the explicit
+    choice via ``CODNA_ADMISSION_MC=numpy``. So the gate can NEVER stall: a kernel hiccup degrades to
+    in-process math, it does not block admission.
+
+Thread-safe: a single lock guards the in-flight counter + the duration window, so it can front a
+thread-pool of fixes.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import threading
+import time
+from collections import deque
+from dataclasses import dataclass
+from typing import Callable
+
+try:
+    import numpy as _np
+except Exception:  # noqa: BLE001 — numpy optional; pure-Python fallback below
+    _np = None
+
+
+# A breach predictor: P(a fix admitted under this contention exceeds the SLA), given the observed
+# duration window, the contention factor, the SLA, and the draw count. Strategies below.
+BreachFn = Callable[[list[float], float, float, int], float]
+
+
+def _numpy_breach_probability(durations: list[float], contention: float, sla: float, n: int) -> float:
+    """Default in-process predictor: empirical bootstrap. Draw base durations from the observed
+    distribution and inflate by the contention factor (fixes share the model rate budget, so each
+    one's wall-clock stretches by ``concurrency / det_cap``). Sub-millisecond, zero network."""
+    if not durations:
+        return 1.0
+    if _np is not None:
+        base = _np.asarray(durations, dtype="float64")
+        draws = _np.random.choice(base, size=n, replace=True) * contention
+        return float((draws > sla).mean())
+    import random
+
+    breaches = sum(1 for _ in range(n) if random.choice(durations) * contention > sla)
+    return breaches / n
+
+
+def mojo_breach_probability(
+    durations: list[float], contention: float, sla: float, n: int, *, client: object | None = None
+) -> float:
+    """Opt-in predictor backed by the engine's compiled ``monte_carlo`` mojo kernel.
+
+    Fits a lognormal to the observed durations (μ = mean(ln d) + ln(contention), σ = stdev(ln d) — a
+    constant scale on a lognormal is an additive shift on μ, matching the numpy path's
+    ``× contention``) and drives ``POST /v1/simulate`` (expert mode) with objective ``sla - duration``.
+    The kernel returns ``metrics.probability_of_loss`` = P(sla - duration < 0) = P(duration > sla) =
+    the breach probability — verified against the live kernel.
+
+    Reached over the LOCAL SDK (loopback daemon, zero network) — the same channel every fix step uses.
+    Raises on any transport/shape error so the caller can fall back to in-process numpy."""
+    import math
+    import statistics
+
+    logs = [math.log(d) for d in durations if d > 0]
+    if not logs:
+        return 1.0
+    mu = statistics.fmean(logs) + math.log(max(contention, 1e-9))
+    sigma = max(statistics.pstdev(logs) if len(logs) > 1 else 0.25, 1e-3)
+    body = {
+        "mode": "expert",
+        "simulation_model": "monte_carlo",
+        "simulation": {
+            "variables": [{"name": "duration", "distribution": "lognormal", "params": {"mean": mu, "std": sigma}}],
+            "objective_function": f"{float(sla)} - duration",
+        },
+        "runs": int(min(max(n, 100), 1_000_000)),
+        "seed": 7,  # deterministic: the window already moves, so a fixed seed keeps the estimate reproducible
+    }
+    if client is None:
+        from codna.cli import _client as _mk
+
+        client = _mk()
+    resp = client._request("POST", "/v1/simulate", json=body)
+    return float(resp["metrics"]["probability_of_loss"])
+
+
+def make_mojo_breach_fn(client: object | None = None, *, fallback: BreachFn = _numpy_breach_probability) -> BreachFn:
+    """Build a ``BreachFn`` that routes to the mojo kernel, falling back to ``fallback`` (numpy by
+    default) on any error so a predictor/engine outage never stalls admission."""
+
+    def _fn(durations: list[float], contention: float, sla: float, n: int) -> float:
+        try:
+            return mojo_breach_probability(durations, contention, sla, n, client=client)
+        except Exception:  # noqa: BLE001 — never let the predictor block the gate
+            return fallback(durations, contention, sla, n)
+
+    return _fn
+
+
+@dataclass
+class AdmissionConfig:
+    ceiling: int = 8                 # hard max concurrency (== sidecar AGENT_CORE_MAX_CONCURRENCY)
+    model_rate_budget: int = 8       # concurrent model calls the provider rate-limit comfortably allows
+    sla_s: float = 900.0             # per-fix wall-clock budget (the timeout)
+    breach_threshold: float = 0.10   # admit in the MC zone only while P(SLA breach) < this
+    trials: int = 4000               # MC draws
+    window: int = 200                # observed-duration ring size
+
+
+@dataclass
+class AdmissionVerdict:
+    admit: bool
+    reason: str
+    in_flight: int
+    det_cap: int
+    p_breach: float | None = None
+
+
+class MCAdmissionDecider:
+    def __init__(self, config: AdmissionConfig | None = None, mc_fn: BreachFn | None = None) -> None:
+        self.cfg = config or AdmissionConfig()
+        # The breach predictor. None → in-process numpy bootstrap; pass make_mojo_breach_fn() to let
+        # Algenta's compiled kernel decide (it already falls back to numpy if the daemon isn't up).
+        self._mc_fn: BreachFn = mc_fn or _numpy_breach_probability
+        self._lock = threading.Lock()
+        self._in_flight = 0
+        self._durations: deque[float] = deque(maxlen=self.cfg.window)
+        self._arrivals: deque[float] = deque(maxlen=self.cfg.window)
+
+    # ── lifecycle the orchestrator calls around each fix ────────────────────────────────────────
+    def start(self) -> None:
+        with self._lock:
+            self._in_flight += 1
+            self._arrivals.append(time.monotonic())
+
+    def finish(self, duration_s: float) -> None:
+        with self._lock:
+            self._in_flight = max(0, self._in_flight - 1)
+            if duration_s > 0:
+                self._durations.append(float(duration_s))
+
+    @property
+    def in_flight(self) -> int:
+        with self._lock:
+            return self._in_flight
+
+    # ── the decision ────────────────────────────────────────────────────────────────────────────
+    def _det_cap(self, model_rate_budget: int | None) -> int:
+        cfg = self.cfg
+        return max(1, min(cfg.ceiling, model_rate_budget if model_rate_budget is not None else cfg.model_rate_budget))
+
+    def _decide(self, inflight: int, durations: list[float], det_cap: int) -> AdmissionVerdict:
+        cfg = self.cfg
+        prospective = inflight + 1
+        if prospective <= det_cap:
+            return AdmissionVerdict(True, "within deterministic capacity", inflight, det_cap)
+        if prospective > cfg.ceiling:
+            return AdmissionVerdict(False, "at hard ceiling", inflight, det_cap)
+        if not durations:
+            # No history yet in the MC zone — be conservative: hold at the deterministic floor.
+            return AdmissionVerdict(False, "no duration history; holding at det_cap", inflight, det_cap)
+        p = self._mc_breach_probability(durations, concurrency=prospective, det_cap=det_cap)
+        if p < cfg.breach_threshold:
+            return AdmissionVerdict(True, f"MC admit (P breach {p:.2f} < {cfg.breach_threshold})", inflight, det_cap, p)
+        return AdmissionVerdict(False, f"MC throttle (P breach {p:.2f} >= {cfg.breach_threshold})", inflight, det_cap, p)
+
+    def can_admit(self, model_rate_budget: int | None = None) -> AdmissionVerdict:
+        """Non-reserving PEEK at the decision (inspection/metrics). To actually take a slot use
+        try_admit()/gate() — they check-and-reserve atomically, avoiding the admit/start race."""
+        det_cap = self._det_cap(model_rate_budget)
+        with self._lock:
+            return self._decide(self._in_flight, list(self._durations), det_cap)
+
+    def try_admit(self, model_rate_budget: int | None = None) -> AdmissionVerdict:
+        """Atomic check-and-reserve: the in-flight slot is taken under the SAME lock as the capacity
+        check, so concurrent callers can't all pass the check before any increments. Pair with
+        finish(duration) when the fix completes (gate() does both)."""
+        det_cap = self._det_cap(model_rate_budget)
+        with self._lock:
+            verdict = self._decide(self._in_flight, list(self._durations), det_cap)
+            if verdict.admit:
+                self._in_flight += 1
+                self._arrivals.append(time.monotonic())
+        return verdict
+
+    def _mc_breach_probability(self, durations: list[float], concurrency: int, det_cap: int) -> float:
+        """P(a fix admitted at this concurrency exceeds the SLA). Contention model: when concurrency
+        exceeds det_cap the shared model throughput stretches each fix's wall-clock by
+        ``concurrency / det_cap`` (fixes share the provider rate budget). The configured predictor
+        (mojo kernel by default, numpy fallback) turns that into a breach probability."""
+        contention = max(1.0, concurrency / det_cap)
+        return self._mc_fn(durations, contention, self.cfg.sla_s, self.cfg.trials)
+
+    def snapshot(self) -> dict:
+        """Lightweight state for metrics/observability."""
+        with self._lock:
+            durs = list(self._durations)
+        return {"in_flight": self._in_flight, "samples": len(durs),
+                "p50_s": (sorted(durs)[len(durs) // 2] if durs else None)}
+
+    @contextlib.contextmanager
+    def gate(self, model_rate_budget: int | None = None, poll_s: float = 1.5, max_wait_s: float = 1800.0):
+        """Wrap a fix: block until admitted (polling the predictive decision), then track the run.
+
+            with decider.gate():
+                run_one_fix()
+
+        Any parallel-fix orchestrator (a batch CLI, the hosted dispatcher, the soak) drops this around
+        each fix; concurrency self-governs to predicted capacity. Raises TimeoutError if never admitted
+        within max_wait_s."""
+        deadline = time.monotonic() + max_wait_s
+        while True:
+            verdict = self.try_admit(model_rate_budget)   # atomic check-and-reserve
+            if verdict.admit:
+                break
+            if time.monotonic() > deadline:
+                raise TimeoutError(f"admission gate timed out: {verdict.reason}")
+            time.sleep(poll_s)
+        started = time.monotonic()
+        try:
+            yield verdict
+        finally:
+            self.finish(time.monotonic() - started)
+
+
+_ADMITTER: MCAdmissionDecider | None = None
+_ADMITTER_LOCK = threading.Lock()
+
+
+def get_admitter() -> MCAdmissionDecider:
+    """Process-wide admitter shared by all concurrent fixes in this process. Tunable via env:
+    CODNA_FIX_CEILING (hard max), CODNA_MODEL_RATE_BUDGET (deterministic floor), CODNA_FIX_SLA_S.
+    Predictor: ``CODNA_ADMISSION_MC`` = ``mojo`` (default — Algenta's compiled kernel via the local
+    SDK, numpy fallback if the daemon isn't up) or ``numpy`` (pure in-process)."""
+    global _ADMITTER
+    if _ADMITTER is None:
+        import os
+        with _ADMITTER_LOCK:
+            if _ADMITTER is None:
+                mc = os.environ.get("CODNA_ADMISSION_MC", "mojo").strip().lower()
+                mc_fn = make_mojo_breach_fn() if mc == "mojo" else _numpy_breach_probability
+                _ADMITTER = MCAdmissionDecider(
+                    AdmissionConfig(
+                        ceiling=int(os.environ.get("CODNA_FIX_CEILING", "8")),
+                        model_rate_budget=int(os.environ.get("CODNA_MODEL_RATE_BUDGET", "4")),
+                        sla_s=float(os.environ.get("CODNA_FIX_SLA_S", "900")),
+                    ),
+                    mc_fn=mc_fn,
+                )
+    return _ADMITTER

codna-0.1.0/codna/agent-core/CLINE_FORK.md

@@ -0,0 +1,55 @@
+# agent-core: forked-Cline vendoring + headless proof
+
+The agent-core sidecar's `runAgent()` (in `run-server.mjs`) is currently a stub. It will be
+backed by a **vendored, Apache-2.0 fork of `@cline/core`** running headless. This note records
+the empirically-verified build recipe and the headless proof so the vendoring step is mechanical.
+
+## Source & license (verified)
+- Upstream: `https://github.com/cline/cline`, Bun monorepo. Spike used HEAD `3a3ea6e`
+  (architecture cross-checked against pinned `1c1ea0bd`).
+- **Root `LICENSE` = Apache-2.0.** BUT `sdk/packages/{core,shared,llms}/package.json` OMIT a
+  `license` field (only `agents` + `sdk` declare `Apache-2.0`). This is why the *npm-published*
+  `@cline/core` reads "Proprietary". **Rule: vendor from the GitHub source (covered by root
+  Apache-2.0), add an explicit `"license": "Apache-2.0"` + header to each vendored package, and
+  NEVER `npm i @cline/*`.** (Release-blocking CI guard = task #4.)
+
+## Build recipe (verified working, Node ≥22 + Bun 1.3.x)
+```sh
+git clone --depth 1 https://github.com/cline/cline.git
+cd cline
+bun install                 # full root install — gets workspace links + tsc (vscode is excluded)
+bun run build:sdk           # = bun --production -F './sdk/packages/*' build  (topological)
+# => sdk/packages/{shared,llms,agents,core,sdk}/dist/index.js all build (exit 0)
+```
+Gotcha: a *filtered* install (`bun install --filter './sdk/packages/*'`) is NOT enough — it omits
+`tsc` and the cross-package workspace links, so the build fails to resolve `@cline/shared`.
+
+The built `core/dist/index.js` **externalizes** its `@cline/*` siblings, so a consumer must have
+them resolvable. In a plain dir, symlink them:
+```sh
+mkdir -p node_modules/@cline
+for p in shared llms agents core sdk; do ln -sfn <repo>/sdk/packages/$p node_modules/@cline/$p; done
+```
+
+## Headless instantiation — PROVEN
+```js
+import { ClineCore } from "@cline/core";
+const cline = await ClineCore.create({ clientName: "algenta-spike", backendMode: "local" });
+// backendMode "local" => in-process LocalRuntimeHost, NO hub daemon, no model, no network.
+// instance API: start, subscribe, restore, disposeSessionBootstrap ; cleanup via dispose().
+await cline.dispose();
+```
+`ClineCoreOptions` (`sdk/packages/core/src/cline-core/types.ts`): `clientName?`, `backendMode?:
+RuntimeHostMode("auto"|"local"|"hub"|"remote")`, `hub?`, `remote?`, `capabilities?`, `prepare?`.
+
+## Next (wire the real adapter — replaces the stub `runAgent`)
+1. Vendor `sdk/packages/{shared,llms,agents,core}` into this fork at a pinned tag (+ Apache headers,
+   strip `shared/src/runtime/cline-environment.ts` + `core/src/services/telemetry/core-events.ts`).
+2. `cline-adapter.ts`: wrap `ClineCore.create({backendMode:"local", capabilities})` + `start()`.
+   - Inject our evidence bundle / blast-radius via the **`capabilities`** option (the verified
+     injection seam — NOT the dead `runtimePlaceholders` path).
+   - Suppress exploration tools at the capability/tool-roster layer (SDK tool names are
+     `bash/editor/read_files/apply_patch/search/fetch_web`, not the classic VS Code names).
+   - Point `@cline/llms` at the loopback OpenAI-compatible model proxy.
+3. Stream `start()` events to the NDJSON `/run` response; agent mutates files under `working_dir`;
+   Python still recomputes the authoritative diff.