ultra-builder-pro-cli 3.0.2 → 5.0.1

package/skills/ultra-delegate/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ultra-delegate
-description: Delegate one bounded workflow segment to another installed CLI in an isolated worktree and return only its stable result artifact. Use when the owner asks for another model or host to execute, review, verify, or continue a specific slice of current work.
+description: Delegate one bounded workflow segment to another installed Agent runtime through a conformance-gated ACP or CLI driver in an isolated worktree, then return only its stable result artifact. Use when the owner asks for another model or host to execute, review, verify, or continue a specific slice of current work.
 ---
 
 # Run a bounded worker without giving it project authority
@@ -14,6 +14,20 @@ another Agent requires the owner-directed OFFER → ACK → RESULT protocol in
 `../ultra-change/references/primary-transfer.md`, which stays mutually exclusive
 with this bounded-worker path.
 
+## Route modes
+
+| Mode | Entry | Observable exit | Next |
+|---|---|---|---|
+| `task` | Explicit owner authorization for one task execution or continuation slice | One validated terminal worker result and isolated diff are returned to the primary writer | Return to the primary `ultra-dev` task for interpretation and integration |
+| `research` | Explicit owner authorization for one active Change's bounded evidence question | One validated terminal result carries the named evidence or a bounded unavailable path | Return to `ultra-research/change-scoped` under the primary writer |
+| `aggregate` | Explicit owner authorization for one Change-level review or verification question | One validated terminal finding result is available without canonical `.ultra` writes | Return to the primary `ultra-test`, `ultra-review`, or requesting route |
+
+Follow `../ultra-status/references/route-contract.md`. Delegation always remains an
+explicit-entry capability, even when the surrounding Change has an Execution Grant.
+Show one Route Card before launch and one after the terminal result. Worker events and
+transport progress may update `Position`, `Delta`, or `Reality`; they never prove the
+delegated slice complete or select the primary route.
+
 ## Before you start
 
 1. Resolve exactly one active `change_id`, then select one scope and name it in
@@ -39,6 +53,8 @@ with this bounded-worker path.
 - No `writable_roots` entry is `.ultra/` or sits under it, and the actual diff touches
   nothing there.
 - Timeout and cancellation reach a terminal failed result and release `run.lock`.
+- ACP updates stay in a derived redacted event journal; no `agent_thought_chunk`, raw tool
+  input/output, credential, session, or stop reason can establish Ultra completion.
 - The primary host verifies the result against the selected scope's task acceptance,
   Research exit evidence, or aggregate review/verification question.
 
@@ -66,15 +82,66 @@ policy.
 Create `.ultra/.runtime/worktrees/<id>` as a real Git worktree and run:
 
 ```text
-ubp delegate run --to <host> --instruction <file> --permission <file> --worktree <dir> --timeout <seconds>
+node <loaded-ultra-delegate-skill-dir>/scripts/delegate.cjs run --to <host> --instruction <file> --permission <file> --worktree <dir> --timeout <seconds>
 ```
 
+Resolve `<loaded-ultra-delegate-skill-dir>` from this Skill's actual loaded path. The
+Skill-local launcher and worker are the canonical runtime. Do not search `PATH` for
+`ubp`, install a global Ultra package, or invoke `npx` to locate Ultra during
+delegation. The Claude and Codex ACP profiles may separately execute their exact pinned
+adapter packages through `npx`; that transport dependency is declared in the profile.
+`ubp delegate ...` is a one-release compatibility wrapper only.
+
 `<host>` is `claude`, `codex`, `opencode`, `kimi`, `grok`, or `zcode`. Kimi accepts an
 optional `--model <id>` when its account has no default headless model. A ZCode primary
 host uses this same command to delegate to any other installed CLI; a different primary
 host can select `--to zcode` through the ZCode headless profile.
 
-The ZCode headless transport is `experimental`: it is an App-internal or PATH CLI with
+The launcher selects one `AgentExecutionDriver` per Host. A stable ACP v1 stdio
+candidate is preferred only when that exact Host's versioned conformance row is
+`passed`, names a non-empty evidence reference, and its executable and declared
+candidate-identity probes succeed. The probes are bounded local version checks; they
+inspect capability, executability, and pinned runtime identity without starting a
+provider task. Every other case uses the
+result-compatible `CliDriver` and records `execution_driver`, `acp_capability`, and the
+exact `driver_fallback_reason` in the receipt and terminal result. Do not edit a
+conformance row merely because a binary or help command exists.
+`ULTRA_DELEGATE_FORCE_CLI=1` is the explicit operator recovery switch: it selects the
+same bounded `CliDriver` with `acp_forced_cli` without deleting the ACP candidate or
+changing its evidence row.
+
+`AcpDriver` sends `initialize` with protocol v1 and no client filesystem, terminal, or
+interactive-auth capability; creates one session at the absolute isolated-worktree
+`cwd`; sends the digest-bound packet as one text prompt; and consumes `session/update`,
+permission, cancellation, and terminal messages. It retains only bounded redacted
+event metadata. An edit/delete/move request is granted with `allow_once` only when all
+declared locations are already inside `writable_roots`; scope widening and execution,
+fetch, mode-switch, or unknown operations are denied and force a typed terminal
+failure. `allow_always` is never selected. If `session/new` reports
+`acp_auth_required` before any prompt is sent, the launcher runs the already-bound
+`CliDriver` once and records the failed ACP attempt as redacted fallback metadata. It
+never retries any post-prompt or other ACP failure, so this recovery cannot duplicate a
+provider task. The driver does not copy or solicit credentials.
+Some agents emit creation-time session metadata before their `session/new` response.
+The driver transiently buffers only a bounded set of metadata update kinds, then checks
+every buffered `sessionId` against the returned identity before publishing an event.
+Early message/tool content, an identity mismatch, or a count/byte overflow fails typed.
+
+The ZCode headless transport is `experimental`: its thin profile invokes the
+independently installed `zcode-acp` v0.1.0 bridge, pinned to source commit
+`42fe149d4b501469343c01f23ba3801832306d53` plus the digest-bound ZCode 0.16.5
+runtime-preferences patch under this Skill's `patches/` directory, and passes only the
+installed ZCode Desktop runtime path (or the operator's explicit PATH/test override).
+Selection verifies both the bridge build marker
+`zcode-acp 0.1.0+ultra.zcode.0.16.5` and the installed runtime version `0.16.5` before
+using the passing receipt.
+Ultra ships the source patch but never redistributes the bridge binary or App bytes.
+Host identity and provider identity are separate; the verified local runtime uses the
+Owner's domestic BigModel provider rather than international Z.AI OAuth. The installed
+`app-server` remains a
+ZCode Protocol surface behind that bridge, not ACP evidence by itself; the ZCode row
+can pass only from its own provider-backed conformance receipt. The runtime remains
+an App-internal or PATH CLI with
 no public stability contract, and it is **not** the documented ZCode Desktop
 interactive surface. `delegate run --to zcode` refuses to launch until the invocation
 explicitly carries `--ack-experimental`; every launch then prints a stderr warning and
@@ -83,10 +150,14 @@ and `experimental_ack: true` in the receipt, the worker spec, and the terminal r
 (including failure and timeout recovery results), so no receipt can imply a documented
 Desktop session. Promotion requires official documentation plus a full recovery drill.
 
-The command returns a receipt. Immediately run `scripts/delegate_wait.py`; read no
-intermediate output. Use `ubp delegate status --delegation <dir>` for a read-only state
-and `ubp delegate cancel --delegation <dir>` to request termination. Never delete a lock
-to manufacture completion.
+The command returns a receipt. `status --delegation <dir>` reports the active driver,
+fallback reason, and latest safe derived ACP observation when present; that observation
+is execution telemetry, not a route or completion verdict. Immediately run
+`python3 <loaded-ultra-delegate-skill-dir>/scripts/delegate_wait.py <result.json>`; read
+no intermediate output. Use the same Skill-local Node entrypoint with `status
+--delegation <dir>` for a read-only state and `cancel --delegation <dir>` to request
+termination. The receipt carries the exact canonical cancel command. Never delete a
+lock to manufacture completion.
 
 The worker returns one schema-constrained JSON final response. The launcher extracts it
 from the host's native structured output, validates digests, process exit, exact schema,
@@ -117,6 +188,8 @@ interpretation, risk acceptance, integration and task state.
 ## References
 
 - `references/delegation-contract.md` — strict permission, receipt and result schemas.
+- `scripts/delegate.cjs` — canonical installed launcher and status/cancel entrypoint.
 - `scripts/delegate_wait.py` — run immediately after the launch receipt.
+- `../ultra-status/references/route-contract.md` — owner-visible route, checkpoint, and recovery output.
 - `../ultra-think/SKILL.md` — read when No Consensus exposes a consequential decision.
 - `../ultra-think/references/autonomy-boundary.md` — read before granting write effects.

package/skills/ultra-delegate/patches/zcode-acp-0.1.0-zcode-0.16.5.patch

@@ -0,0 +1,184 @@
+diff --git a/Cargo.lock b/Cargo.lock
+index bfadfbb..4b1d665 100644
+--- a/Cargo.lock
++++ b/Cargo.lock
+@@ -2492,7 +2492,7 @@ dependencies = [
+ 
+ [[package]]
+ name = "zcode-acp"
+-version = "0.1.0"
++version = "0.1.0+ultra.zcode.0.16.5"
+ dependencies = [
+  "aes-gcm",
+  "agent-client-protocol",
+diff --git a/Cargo.toml b/Cargo.toml
+index f096b91..4b4d985 100644
+--- a/Cargo.toml
++++ b/Cargo.toml
+@@ -1,6 +1,6 @@
+ [package]
+ name = "zcode-acp"
+-version = "0.1.0"
++version = "0.1.0+ultra.zcode.0.16.5"
+ edition = "2024"
+ description = "ACP adapter that bridges Buzz relay events to the ZCode CLI via its stdio app-server"
+ license = "Apache-2.0"
+diff --git a/src/zcode/mod.rs b/src/zcode/mod.rs
+index 7963959..14725bb 100644
+--- a/src/zcode/mod.rs
++++ b/src/zcode/mod.rs
+@@ -266,6 +266,13 @@ impl DriverState {
+                 }
+             }
+             Some(Incoming::ServerRequest { id, method, params }) => {
++                if method == methods::SESSION_REQUEST_RUNTIME_PREFERENCES {
++                    let _ = self.write_tx.send(json!({
++                        "id": id,
++                        "result": default_runtime_preferences(),
++                    }));
++                    return;
++                }
+                 // The ACP layer answers via `reply_tx`; a side task writes the
+                 // reply back through `write_tx` echoing the wire id.
+                 let (reply_tx, reply_rx) = oneshot::channel();
+@@ -373,6 +380,32 @@ impl DriverState {
+     }
+ }
+ 
++fn default_runtime_preferences() -> Value {
++    json!({
++        "nativeSearchEnhancementsEnabled": true,
++        "memoryEnabled": false,
++        "askUserQuestionAutoResolutionEnabled": true,
++        "modelContextBudgetStrategy": "preflight-v1",
++    })
++}
++
++fn bootstrap_server_request_response(id: RequestId, method: &str) -> Value {
++    if method == methods::SESSION_REQUEST_RUNTIME_PREFERENCES {
++        json!({
++            "id": id,
++            "result": default_runtime_preferences(),
++        })
++    } else {
++        json!({
++            "id": id,
++            "error": {
++                "code": -32601,
++                "message": format!("Unsupported app-server request: {method}"),
++            },
++        })
++    }
++}
++
+ /// Run the dispatcher: read framed messages, dispatch each into shared state.
+ async fn run_dispatcher(
+     state: Arc<Mutex<DriverState>>,
+@@ -647,6 +680,15 @@ pub async fn build_session(
+                     protocol::ResponseResult::Ok(v) => break v,
+                     protocol::ResponseResult::Err(e) => return Err(SessionError::CreateFailed(e)),
+                 },
++                Some(Incoming::ServerRequest {
++                    id: request_id,
++                    method,
++                    ..
++                }) => {
++                    write_tx
++                        .send(bootstrap_server_request_response(request_id, &method))
++                        .map_err(|e| SessionError::Send(e.to_string()))?;
++                }
+                 _ => continue,
+             },
+             None => return Err(SessionError::TransportClosed),
+diff --git a/src/zcode/protocol.rs b/src/zcode/protocol.rs
+index 71fa3e9..6e3e595 100644
+--- a/src/zcode/protocol.rs
++++ b/src/zcode/protocol.rs
+@@ -138,6 +138,7 @@ impl IncomingMessage {
+ 
+ pub mod methods {
+     pub const SESSION_CREATE: &str = "session/create";
++    pub const SESSION_REQUEST_RUNTIME_PREFERENCES: &str = "session/requestRuntimePreferences";
+     pub const SESSION_RESUME: &str = "session/resume";
+     pub const SESSION_LIST: &str = "session/list";
+     pub const SESSION_SUBSCRIBE: &str = "session/subscribe";
+diff --git a/tests/acp_client.py b/tests/acp_client.py
+index a407220..0e46772 100644
+--- a/tests/acp_client.py
++++ b/tests/acp_client.py
+@@ -22,6 +22,7 @@ from __future__ import annotations
+ 
+ import json
+ import os
++import select
+ import subprocess
+ import sys
+ from pathlib import Path
+@@ -40,6 +41,9 @@ def send(proc: subprocess.Popen, obj: dict) -> None:
+ 
+ def read_message(proc: subprocess.Popen) -> dict:
+     assert proc.stdout is not None
++    readable, _, _ = select.select([proc.stdout], [], [], 5)
++    if not readable:
++        raise TimeoutError("agent did not emit an ACP message within 5 seconds")
+     raw = proc.stdout.readline()
+     if not raw:
+         raise EOFError("agent closed stdout")
+@@ -74,6 +78,7 @@ def main() -> int:
+         stdin=subprocess.PIPE,
+         stdout=subprocess.PIPE,
+         stderr=sys.stderr,  # surface shim logs inline for debugging
++        bufsize=0,
+     )
+ 
+     try:
+diff --git a/tests/fake-app-server.cjs b/tests/fake-app-server.cjs
+index f6a5991..e690fbe 100644
+--- a/tests/fake-app-server.cjs
++++ b/tests/fake-app-server.cjs
+@@ -21,6 +21,8 @@ const rl = readline.createInterface({ input: process.stdin, terminal: false });
+ let sessionIdCounter = 0;
+ let activeSession = null;
+ let seqCounter = 0;
++let pendingCreateId = null;
++let runtimePreferencesRequestId = null;
+ 
+ function send(obj) {
+   process.stdout.write(JSON.stringify(obj) + "\n");
+@@ -54,10 +56,35 @@ function handle(line) {
+     return;
+   }
+   const { id, method, params } = msg;
++  if (!method && id === runtimePreferencesRequestId) {
++    const prefs = msg.result;
++    const valid = prefs
++      && prefs.nativeSearchEnhancementsEnabled === true
++      && prefs.memoryEnabled === false
++      && prefs.askUserQuestionAutoResolutionEnabled === true
++      && prefs.modelContextBudgetStrategy === "preflight-v1";
++    if (!valid) {
++      send({
++        id: pendingCreateId,
++        error: { code: -32602, message: "Invalid runtime preferences response" },
++      });
++    } else {
++      respond(pendingCreateId, { sessionId: activeSession });
++    }
++    pendingCreateId = null;
++    runtimePreferencesRequestId = null;
++    return;
++  }
+   switch (method) {
+     case "session/create": {
+       activeSession = `sess_fake_${++sessionIdCounter}`;
+-      respond(id, { sessionId: activeSession });
++      pendingCreateId = id;
++      runtimePreferencesRequestId = "server-runtime-preferences-1";
++      send({
++        id: runtimePreferencesRequestId,
++        method: "session/requestRuntimePreferences",
++        params: { sessionId: activeSession, scope: "runtime-materialization" },
++      });
+       break;
+     }
+     case "session/subscribe": {

package/skills/ultra-delegate/references/delegation-contract.md

@@ -1,5 +1,18 @@
 # Delegation artifact contract
 
+## Runtime ownership
+
+The loaded `ultra-delegate` Skill owns `scripts/delegate.cjs`,
+`scripts/delegate-worker.cjs`, `scripts/host-profile.cjs`,
+`scripts/agent-execution-driver.cjs`, `scripts/acp-driver.cjs`,
+`scripts/cli-driver.cjs`, `scripts/acp-conformance.cjs`, and its launch-only profiles.
+Invoke the launcher with the loaded Skill's absolute path. It has no package-root or
+global `ubp` dependency. The Claude and Codex profiles separately invoke exact pinned
+ACP adapter packages through `npx`; no `npx` lookup is used to locate Ultra itself.
+The package `ubp delegate` command is a thin
+one-release compatibility import of the same functions; it contains no launcher or
+worker behavior of its own.
+
 ## Permission
 
 ```json
@@ -61,7 +74,7 @@ the host prompt, extracts this object from native structured output, and adds
 failures also add `failure_type`. A nonzero process cannot publish `finished`.
 
 Every receipt, worker spec, and terminal result also records the transport truth:
-`transport_maturity` (from the shared host profile) and the exact `transport_surface`
+`transport_maturity` (from the Skill-local host profile) and the exact `transport_surface`
 wording. The ZCode headless transport is `experimental` with no public stability
 contract and is not the documented ZCode Desktop interactive surface; launching it
 requires the explicit `--ack-experimental` flag, prints a stderr warning, and stamps
@@ -69,11 +82,57 @@ requires the explicit `--ack-experimental` flag, prints a stderr warning, and st
 internal CLI run as a documented Desktop session — including failure, cancellation,
 and timeout recovery results.
 
+They also record `execution_driver`, `driver_fallback_reason`, and the probed
+`acp_capability`, including candidate-identity validity when the profile declares
+bounded local version probes. ACP results add negotiated `acp_protocol_version`, observed
+`acp_stop_reason`, and `events_file`. These are mechanical observations only. In
+particular, `stopReason: end_turn`, a completed tool call, an ACP plan, or process exit
+cannot synthesize the exact model response above or satisfy its Git-diff validation.
+
+## ACP v1 permission and event boundary
+
+The stdio client advertises no client filesystem, terminal, or terminal-auth
+capability. It creates one fresh session with the isolated worktree as absolute `cwd`,
+an empty MCP-server list, and one digest-bound text prompt. Agent-side file tools remain
+inside the Host process and the existing worktree/diff enforcement remains final.
+
+ACP `session/request_permission` uses least authority:
+
+- read, search, and think may select an offered `allow_once`;
+- edit, delete, and move may select `allow_once` only when every non-empty absolute
+  location is already inside a granted real writable root and outside `.ultra/`;
+- execute, fetch, mode switching, unknown operations, read-only writes, symlink escape,
+  and every other widening select an offered rejection and make the run terminally
+  denied;
+- `allow_always` is never selected; cancellation answers any pending permission request
+  with ACP's `cancelled` outcome.
+
+An agent may send creation-time `available_commands_update`, `current_mode_update`,
+`config_option_update`, or `session_info_update` before the `session/new` response.
+Ultra holds at most 32 such messages and 256 KiB transiently, persists no raw payload,
+and replays them only after every message session ID equals the returned session ID.
+Any other early update kind, identity mismatch, count overflow, or byte overflow is a
+typed failure; pre-session buffering cannot contribute model result text.
+
+`events.jsonl` is bounded disposable telemetry. It stores phase/update type, tool kind
+and status, counts, permission decision/scope, and terminal stop reason. It drops
+`agent_thought_chunk` entirely and never stores message text, titles, raw tool
+input/output, credentials, or protocol wire payloads. Status re-projects the latest
+record through the same fixed safe shape, so a malformed or replaced journal becomes
+`event_journal_malformed` instead of being echoed. Loss of the journal does not affect
+recovery or completion.
+
 ## Recovery
 
 - `status` distinguishes running, cancelling, stalled, and terminal artifacts.
+- ACP status may also expose the latest redacted derived event; it remains non-authoritative.
 - `cancel` writes `cancel.request`; the worker terminates its host process, publishes a
   failed result with `failure_type: cancelled`, and removes `run.lock`.
 - `--timeout` does the same with `failure_type: timeout`.
+- `ULTRA_DELEGATE_FORCE_CLI=1` bypasses ACP selection for one operator-controlled run
+  and records `acp_forced_cli`; it does not mutate the conformance record.
+- `acp_auth_required` reported by `session/new` before any prompt was sent runs the
+  immutable bounded CLI fallback once and records `acp_fallback.prompt_sent: false`.
+  No other ACP failure is retried, preventing duplicate provider work.
 - A stopped worker with no result is recoverable through `cancel`, which finalizes the
   stale run. Retry under a new delegation id and fresh digests.