@miller-tech/uap 1.43.2 → 1.44.0

package/dist/delivery/self-gate.js

@@ -0,0 +1,155 @@
+/**
+ * Self-authored acceptance gate
+ *
+ * When a project exposes no detectable gates (no package.json build/test
+ * scripts — the common case for polyglot CLI tasks), the convergence loop has
+ * nothing to iterate against and degrades to a vacuous single-shot "success".
+ *
+ * This module asks the executor model to author a task-specific verification
+ * script (`.uap-deliver/verify.sh`) that exits 0 iff the task is correctly
+ * completed, using only repo-observable evidence (files, program output) — no
+ * network, no hidden test harness. The script is then registered as a required
+ * gate so deliver converges against it.
+ *
+ * The floor (anti-vacuous) rule: a usable acceptance gate MUST fail on the
+ * current, unsolved repository. If it already passes before the model has done
+ * any work, it is trivial and is regenerated with that feedback. This is what
+ * stops deliver from "converging to 1 immediately": turn 1 cannot pass a gate
+ * that is required to fail at the start.
+ */
+import { spawnSync } from 'child_process';
+import { existsSync, mkdirSync, writeFileSync, chmodSync } from 'fs';
+import { join } from 'path';
+const GATE_DIR = '.uap-deliver';
+const GATE_FILE = 'verify.sh';
+const DEFAULT_ATTEMPTS = 3;
+const DEFAULT_TIMEOUT_MS = 120_000;
+/** Pull a shell script out of a model response (fenced block preferred). */
+export function extractScript(modelOutput) {
+    const fence = modelOutput.match(/```(?:bash|sh|shell)?\s*\n([\s\S]*?)```/);
+    const body = (fence ? fence[1] : modelOutput).trim();
+    // Guarantee a shebang so `bash <file>` and direct exec both behave.
+    if (/^#!/.test(body))
+        return body;
+    return `#!/usr/bin/env bash\n${body}`;
+}
+function buildAuthorPrompt(instruction, projectRoot, priorFeedback) {
+    const retry = priorFeedback
+        ? `\n\nYour previous script was rejected because: ${priorFeedback}\nWrite a stricter script that genuinely verifies the required outcome.`
+        : '';
+    return [
+        'You are writing an ACCEPTANCE TEST for a coding task, not solving it.',
+        '',
+        `TASK:\n${instruction}`,
+        '',
+        `PROJECT ROOT: ${projectRoot}`,
+        '',
+        'Write a self-contained POSIX bash script that:',
+        '  - exits 0 ONLY if the task is fully and correctly completed',
+        '  - exits non-zero otherwise (print a short reason to stderr)',
+        '  - checks concrete, observable evidence: expected files exist, a program',
+        '    builds/runs, output matches what the task requires',
+        '  - uses ONLY the repository and standard tools (no network, no access to',
+        '    any hidden test harness)',
+        '  - is runnable from the project root',
+        '',
+        'CRITICAL: the script must FAIL right now, on the current unsolved repo,',
+        'and only PASS once the task has actually been done. Do not write a check',
+        'that trivially passes (e.g. `exit 0`, or only `test -d .`).',
+        '',
+        'Output ONLY the script inside a single ```bash code block.',
+        retry,
+    ].join('\n');
+}
+/** Run the candidate gate against the current repo state. */
+function runGate(scriptPath, projectRoot, timeoutMs) {
+    const r = spawnSync('bash', [scriptPath], {
+        cwd: projectRoot,
+        timeout: timeoutMs,
+        encoding: 'utf-8',
+        env: { ...process.env, CI: 'true' },
+    });
+    if (r.error) {
+        return { exitCode: null, spawnError: true, outputTail: String(r.error.message).slice(-500) };
+    }
+    const out = `${r.stdout ?? ''}${r.stderr ?? ''}`.slice(-500);
+    return { exitCode: r.status, spawnError: false, outputTail: out };
+}
+/**
+ * Author and validate a task-specific acceptance gate. Retries until the
+ * generated script fails on the current (unsolved) repo — the non-vacuity
+ * floor — or attempts are exhausted.
+ */
+export async function authorAcceptanceGate(opts) {
+    const { instruction, projectRoot, executor } = opts;
+    const attempts = opts.maxAuthorAttempts ?? DEFAULT_ATTEMPTS;
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const notes = [];
+    const gateDir = join(projectRoot, GATE_DIR);
+    const scriptPath = join(gateDir, GATE_FILE);
+    if (!existsSync(gateDir))
+        mkdirSync(gateDir, { recursive: true });
+    let priorFeedback = null;
+    let producedAny = false;
+    for (let attempt = 1; attempt <= attempts; attempt++) {
+        let response;
+        try {
+            response = await executor(buildAuthorPrompt(instruction, projectRoot, priorFeedback));
+        }
+        catch (err) {
+            notes.push(`attempt ${attempt}: model error authoring gate`);
+            priorFeedback = `the authoring call errored (${String(err).slice(0, 80)})`;
+            continue;
+        }
+        const script = extractScript(response);
+        writeFileSync(scriptPath, script, 'utf-8');
+        try {
+            chmodSync(scriptPath, 0o755);
+        }
+        catch {
+            /* non-fatal */
+        }
+        producedAny = true;
+        const run = runGate(scriptPath, projectRoot, timeoutMs);
+        if (run.spawnError) {
+            notes.push(`attempt ${attempt}: gate failed to run (${run.outputTail.slice(0, 80)})`);
+            priorFeedback = 'the script could not execute (syntax/interpreter error)';
+            continue;
+        }
+        if (run.exitCode === 0) {
+            // Vacuous: passes on the unsolved repo. Reject and retry stricter.
+            notes.push(`attempt ${attempt}: gate passed on the UNSOLVED repo — too weak, regenerating`);
+            priorFeedback = 'it passed on the unsolved repository (it must fail until the work is done)';
+            continue;
+        }
+        // Good: a discriminating gate that fails now and must be made to pass.
+        notes.push(`attempt ${attempt}: gate fails on unsolved repo (exit ${run.exitCode}) — accepted`);
+        return {
+            rung: buildRung(scriptPath, timeoutMs),
+            scriptPath,
+            vacuous: false,
+            attempts: attempt,
+            notes,
+        };
+    }
+    // Exhausted attempts. Return the last gate (if any) flagged as vacuous/weak so
+    // the caller can warn; never silently treat absence as success.
+    return {
+        rung: producedAny ? buildRung(scriptPath, timeoutMs) : null,
+        scriptPath: producedAny ? scriptPath : null,
+        vacuous: true,
+        attempts,
+        notes,
+    };
+}
+function buildRung(scriptPath, timeoutMs) {
+    return {
+        id: 'acceptance',
+        name: 'Acceptance check (.uap-deliver/verify.sh)',
+        command: 'bash',
+        args: [scriptPath],
+        required: true,
+        timeoutMs,
+    };
+}
+//# sourceMappingURL=self-gate.js.map

package/dist/delivery/self-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"self-gate.js","sourceRoot":"","sources":["../../src/delivery/self-gate.ts"],"names":[],"mappings":"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"}

package/docs/INDEX.md

@@ -18,6 +18,7 @@ New here? Start with the [project README](../README.md), then [Getting Started](
 
 | Doc | What it covers |
 |---|---|
+| [**What UAP Does Automatically**](guides/AUTOMATIC.md) | Every feature in benefit / when-it-kicks-in terms — install once, it all self-applies ⭐ |
 | [**`uap deliver`**](guides/DELIVER.md) | The delivery harness — convergence loop to verified completion ⭐ |
 | [Memory](guides/MEMORY.md) | The 4-tier memory system, write-gates, semantic recall |
 | [MCP Router](guides/MCP_ROUTER.md) | Token-optimizing tool proxy + FTS5 output compression |
@@ -28,6 +29,7 @@ New here? Start with the [project README](../README.md), then [Getting Started](
 | [Deploy Batching](guides/DEPLOY_BATCHING.md) | Conflict-free batched git/deploy actions |
 | [Coordination](guides/COORDINATION.md) | Multi-agent overlap detection |
 | [Local Models](guides/LOCAL_MODELS.md) | Running agents against local llama.cpp / Qwen models |
+| [Qwen3.6 on llama.cpp by VRAM](guides/QWEN36_LLAMACPP.md) | Tiered 8/12/16/24/32 GB setup; how `uap deliver` uplifts small local models |
 
 ## Architecture
 

package/docs/guides/AUTOMATIC.md

@@ -0,0 +1,92 @@
+# What UAP Does For You — Automatically
+
+> The whole point of UAP: **you install it once, and every feature applies itself
+> as you code.** You don't call commands or remember protocols. UAP watches the
+> coding agent's lifecycle (session start, every prompt, every tool call, every
+> stop) and injects the right help or enforces the right guardrail *at the moment
+> it's needed*.
+
+```bash
+npx @miller-tech/uap init       # one-time, per project
+# …that's it. Open your coding agent and everything below is live.
+```
+
+`init`/`setup` wire UAP into whichever agent you use — Claude Code, Cursor,
+OpenCode, Factory, VSCode, Codex — by installing lifecycle hooks and the MCP
+router. After that the features are **on by default and apply themselves as
+appropriate**. Nothing here needs to be invoked by hand.
+
+---
+
+## How to read this
+
+Two kinds of automatic behaviour, and they're deliberately different:
+
+- **Assist** (dynamic, *helps* you): surfaces the right context — experts,
+  skills, patterns, memories — by *injecting* it where the model will see it.
+  It's confidence-gated, so quiet on conversational turns and rich on real
+  coding tasks. It never blocks; worst case it stays silent.
+- **Enforce** (deterministic, *protects* you): hard guardrails that *block* a
+  tool call when it would violate a rule (edit outside a worktree, skip
+  delivery, run a dangerous command). Each has an escape hatch for the rare
+  sanctioned exception.
+
+For every feature below: **what it does for you**, and **when it kicks in**.
+
+---
+
+## Assist — the right help shows up on its own
+
+| Feature | What it does for you | When it kicks in |
+|---|---|---|
+| **Reactor** (dynamic routing) | On every prompt, surfaces the expert droids, skills, and enforcement patterns relevant to *this* task, so the agent works like it already knows the domain. | Every substantive prompt (`UserPromptSubmit` / per-message). Confidence-gated — silent on "thanks"/"merge it", rich on "fix the auth race condition". |
+| **Memory recall** | Pulls back the lessons, decisions, and gotchas you (or another agent) learned before, so mistakes aren't repeated and context survives across sessions. | Session start (recent + high-importance memories) and per-prompt semantic recall on the task text. |
+| **Pattern RAG** | Injects battle-tested execution patterns (Output-Existence, Decoder-First, Round-Trip verify, …) mined from Terminal-Bench, so the agent uses the approach that actually passes. | Per-prompt, matched to the task; full set retrievable on demand via Qdrant. |
+| **Expert droids** | Routes domain work (security, performance, data, testing, …) to a specialist persona instead of a generalist guess. | When the capability router matches the task's type/files — recommended automatically, with optional auto-spawn above a confidence threshold. |
+| **Skills** | Surfaces the right *procedure* (git-forensics, compression, SQLite-WAL recovery, polyglot, …) for the task at hand. | Per-prompt match against the task; top-N surfaced. |
+| **Model routing** | Picks the right model tier per step (plan with the strong model, execute with the fast one) instead of one model for everything. | On task classification, by complexity and role. |
+
+You don't ask for any of this. It appears in the agent's context the moment the
+task warrants it, and stays out of the way when it doesn't.
+
+---
+
+## Enforce — the guardrails that keep work safe and verified
+
+| Feature | What it does for you | When it kicks in |
+|---|---|---|
+| **Delivery enforcement** (`uap deliver`, **block by default**) | Routes substantive coding through the **convergence loop** — which iterates a model against your real gates (build, type-check, tests) until the change is *verified*, not just plausible. This is what **uplifts small local models well above their weight**: a 3B-active model that would flail on one shot succeeds when driven to green against the gates. | The moment the agent tries to edit a **source** file directly. Docs/configs/scripts/tests are exempt — only real implementation work is gated. Escape: `UAP_DELIVER_BYPASS=1`, or relax with `UAP_ENFORCE_DELIVERY=advisory`. |
+| **Worktree isolation** | Forces code changes into an isolated `.worktrees/NNN-slug/` branch so you never clobber your working tree and every change is a clean, reviewable branch with an auto-PR. | Any source edit outside a worktree is blocked (`PreToolUse`). |
+| **Policy / compliance gates** | Block non-compliant tool calls before they run — dangerous shell (force-push, `terraform apply`), edits that skip a schema diff, plan-before-read violations, etc. | `PreToolUse` on every Edit/Write/Bash/Task call. |
+| **Schema-diff gate** | Flags breaking API/contract changes so you diff-and-verify consumers before shipping them. | After editing a schema/contract file (`*.schema.ts`, `types.ts`, `.proto`, `.graphql`, …). |
+| **Completion gates** | Won't let the agent declare "done" until build/type-check/tests actually pass and a version bump happened. | On `Stop` (end of turn). |
+| **Coordination** | Detects when multiple agents would touch the same files and prevents them stepping on each other. | Session start (register) + work announcement before claiming a task. |
+| **rtk token-optimization** | Rewrites heavy CLI output (git/docker/npm/…) into compact form so the agent burns far fewer tokens reading command output. | Every wrapped CLI command. |
+| **Deploy batching** | Queues changes into conflict-free batched commits/deploys instead of racy one-off pushes. | On `uap deliver --deploy` success. |
+
+Each enforce-gate has a sanctioned escape hatch (an env var) for the rare case
+you genuinely need to bypass it — so the guardrail is firm, not a cage.
+
+---
+
+## Behind it all
+
+| Feature | What it does for you | When it kicks in |
+|---|---|---|
+| **MCP router** | Exposes a tiny meta-tool surface (`discover_tools`/`execute_tool`/`deliver`/`react`) instead of 150+ tools, cutting tool-schema tokens by ~98%. | Wired at install; used whenever the agent discovers/runs a tool. |
+| **HALO trace analysis** | Mines your execution traces for systemic failure modes (loops, stalls) so the harness gets better over time. | Session end / on demand (`uap harness analyze`). |
+| **4-tier memory** | Short-term (recent), long-term (semantic Qdrant), coordination, and patterns — the substrate the recall/pattern features draw from. | Continuously; written on significant decisions, read on recall. |
+
+---
+
+## The one-liner
+
+**Install UAP, then just code.** The assist layer makes your agent act like a
+domain expert with perfect recall; the enforce layer makes sure whatever it
+produces is isolated, verified, and safe — and it drives even small local models
+to *verified* results they couldn't reach in one shot. You never invoke any of
+it; it applies itself, in the right place, at the right time.
+
+See also: [`uap deliver`](DELIVER.md) · [Local Models](LOCAL_MODELS.md) ·
+[Droids & Skills](DROIDS_AND_SKILLS.md) · [Policies](POLICIES.md) ·
+the [Reactor design](../design/UAP_REACTOR.md).

package/docs/guides/LOCAL_MODELS.md

@@ -7,6 +7,11 @@ UAP can drive its coding/convergence loop against **local models** served by
 This keeps inference on your own hardware (zero per-token cost) and works with
 quantized open-weight models such as Qwen 3.x.
 
+> **Just want the recommended local setup?** See
+> [Qwen3.6 35B-A3B on llama.cpp, by VRAM tier](QWEN36_LLAMACPP.md) for
+> copy-paste launch commands for 8 / 12 / 16 / 24 / 32 GB GPUs, and how
+> `uap deliver` uplifts a small local model to *verified* results.
+
 There are two endpoint shapes involved, and it matters which client speaks
 which protocol:
 

package/docs/guides/QWEN36_LLAMACPP.md

@@ -0,0 +1,110 @@
+# Qwen3.6 35B-A3B on llama.cpp, by VRAM tier — with UAP
+
+This is the recommended local stack for UAP: **Qwen3.6 35B-A3B** (a Mixture-of-
+Experts model with only **~3B active parameters** per token) served by
+**llama.cpp**, driven by **UAP's automatic features** — above all `uap deliver`,
+which iterates the model against your real build/test gates until the change is
+*verified*. That convergence loop is what lets a small, cheap, local model
+**punch well above its weight**: one-shot it would flail; driven to green it
+delivers.
+
+Because the active footprint is ~3B, this model runs usefully even on modest
+GPUs by **offloading the (sparse, mostly-idle) expert tensors to system RAM**
+while keeping attention on the GPU. The knob for that is `--n-cpu-moe`.
+
+## Get the model
+
+A 4-bit quant is the sweet spot for coding (quality vs. size). The full weights
+are ~18–19 GB at IQ4_XS:
+
+```
+Qwen3.6-35B-A3B-UD-IQ4_XS.gguf        # ~18–19 GB on disk
+# (a *-MTP.gguf build adds multi-token prediction for faster decode — use it if you have it)
+```
+
+## The base llama-server command
+
+UAP speaks the OpenAI-compatible endpoint, so serve on `:8080/v1`. The flags
+below are the ones that matter; the per-tier table just changes `--n-cpu-moe`,
+`--ctx-size`, and the KV-cache type.
+
+```bash
+llama-server \
+  --model Qwen3.6-35B-A3B-UD-IQ4_XS.gguf \
+  --host 0.0.0.0 --port 8080 \
+  --gpu-layers 99 \              # put all layers on GPU; experts get pulled back by --n-cpu-moe
+  --n-cpu-moe   <PER TIER> \     # how many layers keep their MoE experts in CPU RAM
+  --ctx-size    <PER TIER> \
+  --cache-type-k <q4_0|q8_0> --cache-type-v <q4_0|q8_0> \   # quantize KV cache to save VRAM
+  --flash-attn on \             # faster + less VRAM
+  --jinja \                     # use the model's chat template (REQUIRED for tool calls)
+  --parallel 1
+```
+
+> **`--jinja` / the chat template is non-negotiable for agent use.** Qwen3.6
+> emits *native* OpenAI tool calls, but only when its chat template is active.
+> If tools silently never fire, that's the cause — run `uap tool-calls setup`
+> to install/repair the template, and `uap tool-calls status` to check.
+
+## VRAM tiers
+
+Values are **starting points** — exact `--n-cpu-moe` depends on your build and
+layer count. Rule of thumb: **raise `--n-cpu-moe` if you OOM, lower it for more
+speed.** "System RAM" is what the offloaded experts need *in addition* to the
+GPU.
+
+| VRAM | `--n-cpu-moe` | `--ctx-size` | KV cache | System RAM | What to expect |
+|---|---|---|---|---|---|
+| **8 GB** | `99` (all experts → CPU) | `8192` | `q4_0` | ≥ 32 GB | Attention on GPU, all experts on CPU. Decode is CPU-bandwidth-bound (a few tok/s) — slow but *real*. `uap deliver` makes it productive by driving to verified completion instead of needing a strong one-shot. |
+| **12 GB** | `~36` | `16384` | `q4_0` | ≥ 32 GB | Keep ~the top experts on GPU, rest on CPU. Noticeably faster than 8 GB. |
+| **16 GB** | `~24` | `24576` | `q4_0` | ≥ 24 GB | Roughly half the experts on GPU. Comfortable for most coding tasks. |
+| **24 GB** | *omit* (full model on GPU) | `32768`–`65536` | `q8_0` | 16 GB | **Sweet spot** (RTX 3090/4090). Weights + KV fit on-GPU; use `q8_0` KV for quality, `q4_0` if you want more context. Add `--flash-attn on`. |
+| **32 GB** | *omit* | `131072` | `q8_0`/`f16` | 16 GB | Full model + large context. Add `--parallel 2–4` for concurrent sessions, bump `--batch-size`/`--ubatch-size`. |
+
+Speed extras (any tier): `--flash-attn on` (always), and if your build supports
+it, **self-speculation / MTP** (the `*-MTP.gguf` model, or `--draft-*` flags with
+a tiny draft model) for materially faster decode.
+
+## Point UAP at it
+
+```bash
+# 1) Tell UAP where the model lives (OpenAI-compatible endpoint)
+export UAP_INFERENCE_ENDPOINT="http://localhost:8080/v1"
+#    (or set the endpoint on the model preset in .uap.json / src/models/types.ts)
+
+# 2) Make sure tool calls work
+uap tool-calls setup        # install the chat template + helpers
+uap tool-calls status       # verify
+
+# 3) That's it — code as normal. Everything is automatic from here.
+```
+
+Once installed, **you don't run `uap deliver` by hand** — delivery enforcement
+is on by default, so when your agent goes to implement something it's routed
+through the convergence loop automatically (see
+[What UAP Does For You, Automatically](AUTOMATIC.md)). If you *want* to drive a
+task explicitly:
+
+```bash
+uap deliver "implement a token-bucket rate limiter with tests"
+```
+
+## Why this punches above its weight
+
+A 3B-active model rarely nails a non-trivial change in one shot. UAP changes the
+game without changing the model:
+
+- **`uap deliver`** loops execute → run-the-gates → fix → re-run until build,
+  type-check, and tests all pass — turning "plausible" into "verified".
+- **Pattern RAG + expert routing** (automatic) put the right approach and the
+  right specialist persona in front of the model before it starts.
+- **Memory** stops it re-making the same mistakes across turns and sessions.
+- **Worktree + completion gates** keep every attempt isolated and only let
+  "done" mean *actually done*.
+
+Net effect: a local, zero-per-token, 4-bit MoE model produces verified results
+that a naive one-shot of a much larger model often won't — and it runs on a GPU
+you already own.
+
+See also: [Local Models](LOCAL_MODELS.md) · [`uap deliver`](DELIVER.md) ·
+[Automatic features](AUTOMATIC.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miller-tech/uap",
-  "version": "1.43.2",
+  "version": "1.44.0",
   "description": "Autonomous AI agent memory system with CLAUDE.md protocol enforcement",
   "type": "module",
   "main": "dist/index.js",

package/tools/agents/install-opencode-local.sh.j2

@@ -118,12 +118,17 @@ else
     # -------------------------------------------------------------------
     # NPM REGISTRY MODE: Fallback when no local mount is present
     # -------------------------------------------------------------------
+    # NOTE: the published package is @miller-tech/uap (the old
+    # `universal-agent-protocol` name 404s). Prefer the local /uap-local mount
+    # (handled above + re-installed by the agent after upload); this registry
+    # path is only a last-resort fallback.
     CURRENT_UAP=$(uap --version 2>/dev/null || echo "none")
-    if [ "$CURRENT_UAP" = "$UAP_VERSION" ]; then
-        echo "  UAP v${UAP_VERSION} already installed - skipping"
+    if [ "$CURRENT_UAP" != "none" ]; then
+        echo "  UAP already installed (v${CURRENT_UAP}) - skipping registry fetch"
     else
-        npm i -g universal-agent-protocol@${UAP_VERSION} 2>/dev/null || true
-        echo "  UAP v${UAP_VERSION} installed from npm registry"
+        npm i -g @miller-tech/uap@latest 2>/dev/null \
+            && echo "  UAP installed from npm registry (@miller-tech/uap@latest)" \
+            || echo "  WARNING: UAP npm registry install failed (will rely on /uap-local)"
     fi
 fi
 

package/tools/agents/opencode_uap_agent.py

@@ -1179,6 +1179,10 @@ class OpenCodeUAP(BaseInstalledAgent):
             "tools/agents",
             "tools/uap_harbor",
             "harbor-configs",
+            # Needed so `uap install opencode` can wire the policy gate +
+            # delivery-enforcement enforcer inside the container.
+            "src/policies/enforcers",
+            "src/policies/schemas/policies",
         ]
         local_upload_files = [
             "package.json",
@@ -1227,6 +1231,13 @@ class OpenCodeUAP(BaseInstalledAgent):
 
         logger.info("[Local UAP] Local project uploaded to /uap-local/")
 
+        # NOTE: we deliberately do NOT `npm i -g file:/uap-local` here. The
+        # install script's npm path already globally installs @miller-tech/uap
+        # (with its runtime deps) and runs `uap install opencode`. Re-linking
+        # the global bin to /uap-local — which has no node_modules — would break
+        # the CLI at runtime (ERR_MODULE_NOT_FOUND: commander). The uploaded
+        # /uap-local copy is kept only for Python-side imports / inspection.
+
     def populate_context_post_run(self, context: AgentContext) -> None:
         _parse_token_counts(self.logs_dir, context)
 
@@ -1398,7 +1409,14 @@ class OpenCodeUAP(BaseInstalledAgent):
     def create_run_agent_commands(self, instruction: str) -> list[ExecInput]:
         model = self.model_name or "llama.cpp/qwen35-a3b-iq4xs"
 
-        env = {"OPENCODE_FAKE_VCS": "git"}
+        env = {
+            "OPENCODE_FAKE_VCS": "git",
+            # Transparent delivery: the uap-enforce plugin reads these to run
+            # the `uap deliver` convergence loop on the first source edit.
+            "UAP_DELIVER_ENDPOINT": self._api_endpoint,
+            "UAP_DELIVER_MODEL": os.environ.get("UAP_DELIVER_MODEL", "qwen35-a3b"),
+            "UAP_ENFORCE_DELIVERY": os.environ.get("UAP_ENFORCE_DELIVERY", "block"),
+        }
 
         # --- Step 0: Build classified CLAUDE.md and enhanced instruction ---
         classified_claude_md = build_classified_claude_md(instruction)
@@ -1524,6 +1542,17 @@ class OpenCodeUAP(BaseInstalledAgent):
         # --- Step 5: Environment bootstrapping ---
         commands.append(ExecInput(command=ENV_BOOTSTRAP_CMD))
 
+        # --- Step 5b: Stage raw task instruction for transparent delivery ---
+        # The uap-enforce plugin reads /app/.uap-deliver/task.txt to seed the
+        # `uap deliver` convergence loop on the first source edit.
+        task_b64 = base64.b64encode(instruction.encode()).decode()
+        deliver_task_cmd = (
+            "mkdir -p /app/.uap-deliver && "
+            f"echo '{task_b64}' | base64 -d > /app/.uap-deliver/task.txt && "
+            "echo '[Deliver] task instruction staged for transparent delivery'"
+        )
+        commands.append(ExecInput(command=deliver_task_cmd))
+
         # --- Step 6: Run opencode with enhanced instruction ---
         # opencode.json baseURL points to proxy at http://127.0.0.1:11435/v1
         # which injects tool_choice="required" and forwards to the real LLM

package/tools/agents/plugins/uap-enforce.ts

@@ -41,6 +41,11 @@ export const UapEnforce: Plugin = async ({ $ }) => {
   let totalToolCalls = 0;
   const SOFT_BUDGET = 30;
 
+  // Transparent delivery: the first substantive source edit triggers the
+  // `uap deliver` convergence loop ONCE per session. Guarded so it never
+  // re-enters or fires per-edit.
+  let deliverRan = false;
+
   const TELEMETRY_PATH = '/tmp/uap-telemetry.jsonl';
 
   const simpleHash = (s: string): string => {
@@ -60,6 +65,47 @@ export const UapEnforce: Plugin = async ({ $ }) => {
     'tool.execute.before': async (input, output) => {
       totalToolCalls++;
 
+      // --- Transparent delivery (Layer 5): converge via `uap deliver` ---
+      // When delivery enforcement is active (the UAP default), the FIRST
+      // substantive write/edit hands the task to the `uap deliver` convergence
+      // loop, which iterates the model against the project's real gates
+      // (build/typecheck/test) before the agent's own edit lands. This is how
+      // deliver "uplifts" a small local model: plausible -> verified. It runs
+      // exactly once per session; the original edit then proceeds normally.
+      // Escape hatches: UAP_ENFORCE_DELIVERY=advisory or UAP_DELIVER_BYPASS=1.
+      if (
+        !deliverRan &&
+        (input.tool === 'write' || input.tool === 'edit') &&
+        process.env.UAP_ENFORCE_DELIVERY !== 'advisory' &&
+        !process.env.UAP_DELIVER_BYPASS
+      ) {
+        deliverRan = true; // set first — prevents re-entry / per-edit loops
+        try {
+          const endpoint = process.env.UAP_DELIVER_ENDPOINT || '';
+          const model = process.env.UAP_DELIVER_MODEL || 'qwen35-a3b';
+          const endpointArg = endpoint ? `--endpoint ${endpoint}` : '';
+          const deliverScript =
+            'source $HOME/.nvm/nvm.sh 2>/dev/null || true; ' +
+            'TASK="$(cat /app/.uap-deliver/task.txt 2>/dev/null)"; ' +
+            'if [ -n "$TASK" ] && command -v uap >/dev/null 2>&1; then ' +
+            `echo "[Deliver] converging via uap deliver (model ${model})..."; ` +
+            `UAP_DELIVER_ACTIVE=1 uap deliver "$TASK" ${endpointArg} --model ${model} ` +
+            '--project-root /app --max-turns 5 --no-until-delivered ' +
+            '> /logs/agent/uap-deliver.log 2>&1 || true; ' +
+            'echo "[Deliver] convergence loop finished"; ' +
+            'else echo "[Deliver] skipped (no task file or uap CLI absent)"; fi';
+          await $`bash -lc ${deliverScript}`.nothrow();
+          await $`echo ${JSON.stringify(
+            JSON.stringify({ event: 'transparent_deliver', tool: input.tool, ts: new Date().toISOString() })
+          )} >> ${TELEMETRY_PATH}`
+            .quiet()
+            .nothrow();
+        } catch {
+          /* fail open — let the original edit proceed */
+        }
+        // fall through: the agent's own edit still executes
+      }
+
       // --- Worktree enforcement (Layer 4) ---
       // Warn when file writes happen outside a worktree
       if ((input.tool === 'write' || input.tool === 'edit') && output.args?.filePath) {