From bdda79e82348e76a4e34e199661fae1e86362fdb Mon Sep 17 00:00:00 2001
From: Hanwen Cheng <heawen.cheng@gmail.com>
Date: Sun, 31 May 2026 15:52:17 +0800
Subject: [PATCH 01/23] =?UTF-8?q?feat:=20full=20=C2=A710.2=20HDKD=20agent?=
 =?UTF-8?q?=20bootstrap=20=E2=80=94=20broker=20link-code=20endpoints=20+?=
 =?UTF-8?q?=20daemon=20redeem=20(#144)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Converges the PR #141 interim §10.2 to the literal ceremony: the master mints a
one-time link code bound to a hard-derived child omni
O_agent = SHA256("agentkeys-hdkd-v1" || O_master || "//label"); the agent daemon
generates its own K10 in the sandbox, redeems the code (pop_sig), and the broker
mints J1_agent carrying the HDKD omni + parent lineage. The master then approves
the binding + scope async (push → one Touch ID), iOS/Android-style.

- core: device_crypto (shared K10 keygen / EIP-191 / ecrecover / pop_sig + DeviceKey)
  + HDKD child_omni/child_omni_hex + validate_label (frozen vectors)
- broker: POST /v1/agent/create (J1_master-gated), POST /v1/auth/link-code/redeem
  (pop_sig verified before consume → retryable), GET /v1/agent/pending-bindings;
  SQLite link-code + pending-binding store; AgentKeysClaims + mint_agent_session_jwt;
  mint-oidc-jwt now reads actor_omni from the verified claim (STS-relay prerequisite;
  wallet sessions byte-identical, regression-tested)
- daemon: --init-link-code one-shot (in-sandbox keygen → redeem → persist J1_agent
  → emit binding artifact)
- cli: agentkeys agent create + agent pending (master-side)
- harness: Phase P rework — P.0 create (real broker code) → P.1 install (daemon
  --init-link-code) → P.2 bind → P.3 grant; build + upload the daemon binary
- ci / broker-setup: §10.2 route smoke (401 = live, 404 = stale binary) + nm symbol
  check in setup-broker-host.sh; bump the deploy job timeout 15→25min + SSM
  executionTimeout 900→1500 for the larger broker build closure (agentkeys-core)
- docs: arch.md §10.2 (async master-submits ceremony), §5 agent_omni row, §6.2,
  route list; operator-runbook-wire.md Phase P + troubleshooting; new
  docs/spec/plans/issue-144-hdkd-agent-bootstrap.md

Decisions (master submits the on-chain binding — no contract change; child omni is
public + recomputable; daemon owns keygen+redeem with shared core) and deviations
are recorded in docs/spec/plans/issue-144-hdkd-agent-bootstrap.md.

Tests: core 141; broker 179 lib + agent_bootstrap_flow integration + oidc regression;
clippy -D warnings clean (default features); cargo fmt clean; harness bash -n OK.
---
 .github/workflows/harness-ci.yml              |  21 +-
 Cargo.lock                                    |   1 +
 crates/agentkeys-broker-server/Cargo.toml     |   4 +
 crates/agentkeys-broker-server/src/boot.rs    |  21 +-
 .../src/handlers/agent/create.rs              |  79 ++++
 .../src/handlers/agent/mod.rs                 |  41 ++
 .../src/handlers/agent/pending.rs             |  49 +++
 .../src/handlers/agent/redeem.rs              | 109 +++++
 .../src/handlers/grant/mod.rs                 |   4 +-
 .../src/handlers/mod.rs                       |   1 +
 .../src/handlers/oidc.rs                      |  82 +++-
 .../agentkeys-broker-server/src/jwt/issue.rs  |  44 ++
 .../agentkeys-broker-server/src/jwt/verify.rs |  14 +
 crates/agentkeys-broker-server/src/lib.rs     |  15 +
 crates/agentkeys-broker-server/src/main.rs    |   1 +
 crates/agentkeys-broker-server/src/state.rs   |   8 +-
 .../src/storage/link_codes.rs                 | 413 ++++++++++++++++++
 .../src/storage/mod.rs                        |   4 +
 .../tests/agent_bootstrap_flow.rs             | 300 +++++++++++++
 .../tests/auth_wallet_flow.rs                 |   3 +
 .../tests/email_flow.rs                       |   3 +
 .../tests/grant_flow.rs                       |   3 +
 .../tests/oauth2_flow.rs                      |   3 +
 .../tests/oidc_flow.rs                        |   3 +
 .../tests/wallet_flow.rs                      |   3 +
 crates/agentkeys-cli/src/agent_admin.rs       |  80 ++++
 crates/agentkeys-cli/src/lib.rs               |   1 +
 crates/agentkeys-cli/src/main.rs              |  62 +++
 crates/agentkeys-core/Cargo.toml              |   3 +
 crates/agentkeys-core/src/actor_omni.rs       | 124 ++++++
 crates/agentkeys-core/src/device_crypto.rs    | 277 ++++++++++++
 crates/agentkeys-core/src/lib.rs              |   1 +
 crates/agentkeys-daemon/src/main.rs           | 143 +++++-
 docs/arch.md                                  |  78 ++--
 docs/operator-runbook-wire.md                 |  15 +-
 .../plans/issue-144-hdkd-agent-bootstrap.md   |  55 +++
 harness/phase1-wire-demo.sh                   | 125 ++++--
 scripts/setup-broker-host.sh                  |  29 ++
 38 files changed, 2113 insertions(+), 109 deletions(-)
 create mode 100644 crates/agentkeys-broker-server/src/handlers/agent/create.rs
 create mode 100644 crates/agentkeys-broker-server/src/handlers/agent/mod.rs
 create mode 100644 crates/agentkeys-broker-server/src/handlers/agent/pending.rs
 create mode 100644 crates/agentkeys-broker-server/src/handlers/agent/redeem.rs
 create mode 100644 crates/agentkeys-broker-server/src/storage/link_codes.rs
 create mode 100644 crates/agentkeys-broker-server/tests/agent_bootstrap_flow.rs
 create mode 100644 crates/agentkeys-cli/src/agent_admin.rs
 create mode 100644 crates/agentkeys-core/src/device_crypto.rs
 create mode 100644 docs/spec/plans/issue-144-hdkd-agent-bootstrap.md

diff --git a/.github/workflows/harness-ci.yml b/.github/workflows/harness-ci.yml
index 86bbcf3c..960b4d29 100644
--- a/.github/workflows/harness-ci.yml
+++ b/.github/workflows/harness-ci.yml
@@ -260,7 +260,12 @@ jobs:
       (needs.detect-changes.outputs.broker_changed == 'true' ||
        (github.event_name == 'workflow_dispatch' && inputs.force_deploy_broker == 'true'))
     runs-on: ubuntu-latest
-    timeout-minutes: 15
+    # 25min (was 15): issue #144 adds agentkeys-core to the broker's build closure
+    # (aws-sdk-s3, keyring/zbus, aes-gcm, …), so a COLD cargo cache rebuild runs
+    # longer. Warm (sccache) builds are still ~3min; this headroom only matters on
+    # the first build after a dep change, and prevents the GH-job-cancels-a-still-
+    # running-build race that flaked PR #141's first attempt.
+    timeout-minutes: 25
     permissions:
       id-token: write
       contents: read
@@ -408,7 +413,7 @@ jobs:
           # expansion (no modifier bugs per CLAUDE.md heredoc-trap rule).
           params=$(jq -n --arg script "$deploy_script" '{
             commands: [$script],
-            executionTimeout: ["900"]
+            executionTimeout: ["1500"]
           }')
 
           cmd_id=$(aws ssm send-command \
@@ -428,10 +433,12 @@ jobs:
           INSTANCE_ID: ${{ secrets.TEST_BROKER_INSTANCE_ID }}
         run: |
           set -euo pipefail
-          # Poll every 10s for up to 15 min. The command runs setup-broker-host.sh
-          # which rebuilds + restarts broker/signer/4 workers; cold cargo cache
-          # can be ~10min, warm ~3min.
-          for i in $(seq 1 90); do
+          # Poll every 10s for up to 25 min. The command runs setup-broker-host.sh
+          # which rebuilds + restarts broker/signer/4 workers; a cold cargo cache
+          # is longer since issue #144 grew the broker's dep closure (agentkeys-core
+          # → aws-sdk-s3 / keyring / aes-gcm), warm (sccache) ~3min. Must stay ≤ the
+          # job timeout-minutes (25) and the SSM executionTimeout (1500s).
+          for i in $(seq 1 150); do
             sleep 10
             status=$(aws ssm get-command-invocation \
               --region "$REGION" \
@@ -469,7 +476,7 @@ jobs:
                 ;;
             esac
           done
-          echo "::error::SSM command $SSM_COMMAND_ID did not complete within 15min"
+          echo "::error::SSM command $SSM_COMMAND_ID did not complete within 25min"
           exit 1
 
   harness-e2e:
diff --git a/Cargo.lock b/Cargo.lock
index 20dc1dd1..0c072289 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -42,6 +42,7 @@ name = "agentkeys-broker-server"
 version = "0.1.0"
 dependencies = [
  "agentkeys-broker-server",
+ "agentkeys-core",
  "agentkeys-mock-server",
  "agentkeys-types",
  "anyhow",
diff --git a/crates/agentkeys-broker-server/Cargo.toml b/crates/agentkeys-broker-server/Cargo.toml
index 49aef69d..6ebfe507 100644
--- a/crates/agentkeys-broker-server/Cargo.toml
+++ b/crates/agentkeys-broker-server/Cargo.toml
@@ -13,6 +13,10 @@ path = "src/lib.rs"
 
 [dependencies]
 agentkeys-types = { workspace = true }
+# Issue #144 — shared device_crypto (EIP-191 ecrecover for link-code redeem
+# pop_sig verify) + HDKD child_omni derivation. One source of truth across
+# daemon/CLI/broker.
+agentkeys-core = { workspace = true }
 axum = { version = "0.7", features = ["json"] }
 tokio = { workspace = true }
 serde = { workspace = true }
diff --git a/crates/agentkeys-broker-server/src/boot.rs b/crates/agentkeys-broker-server/src/boot.rs
index 363d9d86..d6ceef67 100644
--- a/crates/agentkeys-broker-server/src/boot.rs
+++ b/crates/agentkeys-broker-server/src/boot.rs
@@ -29,7 +29,7 @@ use crate::jwt::SessionKeypair;
 use crate::oidc::OidcKeypair;
 use crate::plugins::audit::{AuditAnchor, AuditPolicy};
 use crate::plugins::PluginRegistry;
-use crate::storage::{AuthNonceStore, GrantStore, IdentityLinkStore, WalletStore};
+use crate::storage::{AuthNonceStore, GrantStore, IdentityLinkStore, LinkCodeStore, WalletStore};
 
 /// Outcome of the synchronous Tier-1 boot phase.
 pub struct BootArtifacts {
@@ -41,6 +41,8 @@ pub struct BootArtifacts {
     pub nonce_store: Arc<AuthNonceStore>,
     pub grant_store: Arc<GrantStore>,
     pub identity_link_store: Arc<IdentityLinkStore>,
+    /// §10.2 agent-bootstrap link-code + pending-binding store (issue #144).
+    pub link_code_store: Arc<LinkCodeStore>,
     /// Concrete EmailLink plugin handle (Phase A.1, US-018). Populated
     /// when `email_link` is in `BROKER_AUTH_METHODS` AND the
     /// `auth-email-link` feature is compiled in. The registry's auth
@@ -183,6 +185,14 @@ pub fn run_tier1(config: &BrokerConfig) -> anyhow::Result<BootArtifacts> {
             )
         })?,
     );
+    let link_code_store = Arc::new(LinkCodeStore::open(&link_codes_path(config)).map_err(|e| {
+        boot_fail(
+            env::BROKER_AUDIT_DB_PATH,
+            &config.audit_db_path.display().to_string(),
+            format!("LinkCodeStore: {}", e),
+            "link-codes-db",
+        )
+    })?);
 
     // 5. Validate + parse plugin selection env vars. Every name in each
     //    list must resolve at compile time (i.e. the corresponding
@@ -225,6 +235,7 @@ pub fn run_tier1(config: &BrokerConfig) -> anyhow::Result<BootArtifacts> {
         nonce_store,
         grant_store,
         identity_link_store,
+        link_code_store,
         #[cfg(feature = "auth-email-link")]
         email_link: built.email_link,
         #[cfg(feature = "auth-oauth2")]
@@ -300,6 +311,14 @@ fn identity_links_path(config: &BrokerConfig) -> std::path::PathBuf {
         .unwrap_or_else(|| std::path::PathBuf::from("identity_links.sqlite"))
 }
 
+fn link_codes_path(config: &BrokerConfig) -> std::path::PathBuf {
+    config
+        .audit_db_path
+        .parent()
+        .map(|p| p.join("link_codes.sqlite"))
+        .unwrap_or_else(|| std::path::PathBuf::from("link_codes.sqlite"))
+}
+
 #[cfg(feature = "audit-sqlite")]
 fn open_sqlite_anchor(config: &BrokerConfig) -> Result<Arc<dyn AuditAnchor>, anyhow::Error> {
     use crate::plugins::audit::sqlite::SqliteAnchor;
diff --git a/crates/agentkeys-broker-server/src/handlers/agent/create.rs b/crates/agentkeys-broker-server/src/handlers/agent/create.rs
new file mode 100644
index 00000000..374ec76a
--- /dev/null
+++ b/crates/agentkeys-broker-server/src/handlers/agent/create.rs
@@ -0,0 +1,79 @@
+//! `POST /v1/agent/create` — master mints a one-time link code (issue #144 §10.2).
+//!
+//! Gated by the master's `J1` session bearer. Derives the HDKD child omni
+//! `O_agent = SHA256(HDKD_DOMAIN || O_master || "//label")`, mints a single-use
+//! link code bound to it (TTL 600s), and records the scope the master wants the
+//! agent to have (like an app manifest). The master hands the code to the agent
+//! out-of-band; the agent redeems it at `/v1/auth/link-code/redeem`.
+
+use axum::{extract::State, http::HeaderMap, http::StatusCode, response::IntoResponse, Json};
+use serde::Deserialize;
+use serde_json::json;
+
+use crate::error::BrokerError;
+use crate::handlers::agent::unix_now;
+use crate::handlers::grant::{random_b64url, require_session_jwt};
+use crate::state::SharedState;
+use crate::storage::LINK_CODE_TTL_SECONDS;
+
+#[derive(Debug, Deserialize)]
+pub struct AgentCreateBody {
+    /// HDKD child label, e.g. `"agent-a"` (`^[a-z0-9-]{1,32}$`).
+    pub label: String,
+    /// Scope the master intends to grant the agent (the "app manifest").
+    /// Defaults to `"memory"`. Comma-separated service list mirrors
+    /// `heima-scope-set.sh --services`.
+    #[serde(default)]
+    pub requested_scope: Option<String>,
+}
+
+pub async fn agent_create(
+    State(state): State<SharedState>,
+    headers: HeaderMap,
+    Json(body): Json<AgentCreateBody>,
+) -> Result<impl IntoResponse, BrokerError> {
+    let session = require_session_jwt(&headers, &state)?;
+    let master_omni = session.agentkeys.omni_account;
+
+    agentkeys_core::actor_omni::validate_label(&body.label)
+        .map_err(|e| BrokerError::BadRequest(format!("invalid label: {e}")))?;
+    let child_omni = agentkeys_core::actor_omni::child_omni_hex(&master_omni, &body.label)
+        .map_err(|e| BrokerError::BadRequest(format!("derive child omni: {e}")))?;
+
+    let requested_scope = body
+        .requested_scope
+        .filter(|s| !s.trim().is_empty())
+        .unwrap_or_else(|| "memory".to_string());
+
+    let link_code = random_b64url(32);
+    let now = unix_now()?;
+    let expires_at = now + LINK_CODE_TTL_SECONDS;
+    state.link_code_store.issue(
+        &link_code,
+        &child_omni,
+        &master_omni,
+        &body.label,
+        &requested_scope,
+        now,
+        expires_at,
+    )?;
+
+    tracing::info!(
+        operator_omni = %master_omni,
+        child_omni = %child_omni,
+        label = %body.label,
+        "issued §10.2 agent link code"
+    );
+
+    Ok((
+        StatusCode::OK,
+        Json(json!({
+            "link_code": link_code,
+            "child_omni": child_omni,
+            "operator_omni": master_omni,
+            "label": body.label,
+            "requested_scope": requested_scope,
+            "expires_at": expires_at,
+        })),
+    ))
+}
diff --git a/crates/agentkeys-broker-server/src/handlers/agent/mod.rs b/crates/agentkeys-broker-server/src/handlers/agent/mod.rs
new file mode 100644
index 00000000..3c7bf1dd
--- /dev/null
+++ b/crates/agentkeys-broker-server/src/handlers/agent/mod.rs
@@ -0,0 +1,41 @@
+//! §10.2 agent-bootstrap endpoints (issue #144).
+//!
+//! Three endpoints implement the link-code ceremony with the master submitting
+//! the on-chain binding (decision 1 — no contract change, no broker chain key):
+//!
+//! - `POST /v1/agent/create` (master, `J1_master`-gated) — mint a one-time link
+//!   code bound to the HDKD child omni `O_agent = SHA256(.. || O_master || "//label")`.
+//! - `POST /v1/auth/link-code/redeem` (agent, no bearer) — verify the agent's
+//!   `pop_sig`, consume the code, mint `J1_agent`, and stash the device artifact
+//!   as a pending binding.
+//! - `GET /v1/agent/pending-bindings` (master, `J1_master`-gated) — pull the
+//!   redeemed-but-unbound rows to approve (the push-notification substrate).
+//!
+//! The broker never K11-verifies on the agent path — agents are K10-only per the
+//! contract (`registerAgentDevice` writes `k11CredId = 0`). The master's K11
+//! gesture happens later, when it submits the on-chain binding + scope grant.
+
+pub mod create;
+pub mod pending;
+pub mod redeem;
+
+use std::time::{SystemTime, UNIX_EPOCH};
+
+use crate::error::{BrokerError, BrokerResult};
+
+/// Unix seconds, mapped to `BrokerError::Internal` on the (impossible) clock-skew error.
+pub(crate) fn unix_now() -> BrokerResult<i64> {
+    Ok(SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map_err(|e| BrokerError::Internal(format!("clock before unix epoch: {e}")))?
+        .as_secs() as i64)
+}
+
+/// Session-JWT TTL (seconds) for `J1_agent` — same env + default as the wallet
+/// session path (`wallet_verify`), so agent and master sessions age uniformly.
+pub(crate) fn session_jwt_ttl_seconds() -> u64 {
+    std::env::var(crate::env::BROKER_SESSION_JWT_TTL_SECONDS)
+        .ok()
+        .and_then(|s| s.parse::<u64>().ok())
+        .unwrap_or(18_000)
+}
diff --git a/crates/agentkeys-broker-server/src/handlers/agent/pending.rs b/crates/agentkeys-broker-server/src/handlers/agent/pending.rs
new file mode 100644
index 00000000..116de32d
--- /dev/null
+++ b/crates/agentkeys-broker-server/src/handlers/agent/pending.rs
@@ -0,0 +1,49 @@
+//! `GET /v1/agent/pending-bindings` — master pulls redeemed-but-unbound agents
+//! (issue #144 §10.2).
+//!
+//! Gated by the master's `J1` session bearer. Returns the operator's rows that
+//! have been redeemed (`device_pubkey` + `pop_sig` captured) but not yet bound
+//! on-chain — i.e. "agent-A wants to pair + wants `[requested_scope]`". This is
+//! the substrate the production push notification carries; the master pulls it,
+//! then approves with one K11 gesture (bind + scope). `device_key_hash` is
+//! pre-computed so the master can submit `registerAgentDevice` without recomputing.
+
+use axum::{extract::State, http::HeaderMap, http::StatusCode, response::IntoResponse, Json};
+use serde_json::json;
+
+use crate::error::BrokerError;
+use crate::handlers::grant::require_session_jwt;
+use crate::state::SharedState;
+
+pub async fn pending_bindings(
+    State(state): State<SharedState>,
+    headers: HeaderMap,
+) -> Result<impl IntoResponse, BrokerError> {
+    let session = require_session_jwt(&headers, &state)?;
+    let master_omni = session.agentkeys.omni_account;
+
+    let rows = state.link_code_store.pending_bindings(&master_omni)?;
+    let pending: Vec<_> = rows
+        .into_iter()
+        .map(|b| {
+            // Best-effort device_key_hash so the master needn't recompute. A
+            // malformed stored address (shouldn't happen — it round-tripped
+            // through redeem) degrades to an empty string rather than failing
+            // the whole list.
+            let device_key_hash = agentkeys_core::device_crypto::device_key_hash(&b.device_pubkey)
+                .unwrap_or_default();
+            json!({
+                "link_code": b.link_code,
+                "child_omni": b.child_omni,
+                "operator_omni": b.operator_omni,
+                "label": b.label,
+                "requested_scope": b.requested_scope,
+                "device_pubkey": b.device_pubkey,
+                "pop_sig": b.pop_sig,
+                "device_key_hash": device_key_hash,
+            })
+        })
+        .collect();
+
+    Ok((StatusCode::OK, Json(json!({ "pending": pending }))))
+}
diff --git a/crates/agentkeys-broker-server/src/handlers/agent/redeem.rs b/crates/agentkeys-broker-server/src/handlers/agent/redeem.rs
new file mode 100644
index 00000000..ab743d7f
--- /dev/null
+++ b/crates/agentkeys-broker-server/src/handlers/agent/redeem.rs
@@ -0,0 +1,109 @@
+//! `POST /v1/auth/link-code/redeem` — agent redeems the link code (issue #144 §10.2).
+//!
+//! No bearer: the link code IS the bearer secret (one-time, TTL-bounded). The
+//! agent proves possession of its K10 device key via `pop_sig`. On success the
+//! broker mints `J1_agent` (HDKD omni, decoupled from any wallet) and records
+//! the device artifact as a pending binding for the master to approve.
+//!
+//! Order matters: `pop_sig` is verified BEFORE the code is consumed, so an
+//! invalid signature does NOT burn the (single-use) code — the agent can retry.
+//! `pop_sig` proves device-key possession; the link code proves authorization.
+
+use axum::{extract::State, http::StatusCode, response::IntoResponse, Json};
+use serde::Deserialize;
+use serde_json::json;
+
+use crate::error::BrokerError;
+use crate::handlers::agent::{session_jwt_ttl_seconds, unix_now};
+use crate::jwt::issue::mint_agent_session_jwt;
+use crate::state::SharedState;
+use crate::storage::LinkCodeConsume;
+
+#[derive(Debug, Deserialize)]
+pub struct RedeemBody {
+    pub link_code: String,
+    /// The agent's K10 EVM address (`0x` + 40 hex).
+    pub device_pubkey: String,
+    /// EIP-191 `pop_sig` over `keccak256("agentkeys-agent-pop:" || device_key_hash)`.
+    pub pop_sig: String,
+}
+
+pub async fn link_code_redeem(
+    State(state): State<SharedState>,
+    Json(body): Json<RedeemBody>,
+) -> Result<impl IntoResponse, BrokerError> {
+    // 1. Verify pop_sig FIRST (stateless — doesn't touch the code), so a bad sig
+    //    leaves the single-use code unconsumed and retryable.
+    let device_key_hash = agentkeys_core::device_crypto::device_key_hash(&body.device_pubkey)
+        .map_err(|e| BrokerError::BadRequest(format!("bad device_pubkey: {e}")))?;
+    let pop_payload = agentkeys_core::device_crypto::agent_pop_payload(&device_key_hash);
+    let recovered = agentkeys_core::device_crypto::ecrecover_eip191(&pop_payload, &body.pop_sig)
+        .map_err(|e| BrokerError::Unauthorized(format!("pop_sig verify: {e}")))?;
+    if recovered.to_lowercase() != body.device_pubkey.to_lowercase() {
+        return Err(BrokerError::Unauthorized(format!(
+            "pop_sig does not recover to device_pubkey: claimed={}, recovered={recovered}",
+            body.device_pubkey
+        )));
+    }
+
+    // 2. Atomically consume the code (single-use, TTL-bounded), capturing the
+    //    device artifact onto the row as a pending binding.
+    let now = unix_now()?;
+    let (child_omni, operator_omni, label) = match state.link_code_store.consume(
+        &body.link_code,
+        &body.device_pubkey,
+        &body.pop_sig,
+        now,
+    )? {
+        LinkCodeConsume::Available {
+            child_omni,
+            operator_omni,
+            label,
+            ..
+        } => (child_omni, operator_omni, label),
+        LinkCodeConsume::Expired => {
+            return Err(BrokerError::Unauthorized(
+                "link code expired (>600s after issue)".into(),
+            ));
+        }
+        LinkCodeConsume::NotFoundOrConsumed => {
+            return Err(BrokerError::Unauthorized(
+                "link code unknown or already redeemed".into(),
+            ));
+        }
+    };
+
+    // 3. Mint J1_agent (HDKD omni + lineage). The agent authenticates with this
+    //    immediately, but has NO scope until the master approves the binding.
+    let derivation_path = format!("//{label}");
+    let session_jwt = mint_agent_session_jwt(
+        &state.session_keypair,
+        &state.config.oidc_issuer,
+        &child_omni,
+        &operator_omni,
+        &derivation_path,
+        &body.device_pubkey,
+        session_jwt_ttl_seconds(),
+    )
+    .map_err(|e| BrokerError::Internal(format!("mint J1_agent: {e}")))?;
+
+    tracing::info!(
+        operator_omni = %operator_omni,
+        child_omni = %child_omni,
+        label = %label,
+        device = %body.device_pubkey,
+        "redeemed §10.2 link code — J1_agent minted, pending binding recorded"
+    );
+
+    Ok((
+        StatusCode::OK,
+        Json(json!({
+            "session_jwt": session_jwt,
+            "child_omni": child_omni,
+            "operator_omni": operator_omni,
+            "label": label,
+            "derivation_path": derivation_path,
+            "device_key_hash": device_key_hash,
+        })),
+    ))
+}
diff --git a/crates/agentkeys-broker-server/src/handlers/grant/mod.rs b/crates/agentkeys-broker-server/src/handlers/grant/mod.rs
index 005011be..04f98957 100644
--- a/crates/agentkeys-broker-server/src/handlers/grant/mod.rs
+++ b/crates/agentkeys-broker-server/src/handlers/grant/mod.rs
@@ -26,8 +26,8 @@ pub(crate) fn random_b64url(byte_len: usize) -> String {
 }
 
 /// Extract + verify a session JWT from `Authorization: Bearer <jwt>`.
-/// Used by every grant endpoint.
-pub(super) fn require_session_jwt(
+/// Used by every grant endpoint and by the §10.2 agent handlers (issue #144).
+pub(crate) fn require_session_jwt(
     headers: &HeaderMap,
     state: &SharedState,
 ) -> Result<SessionClaims, BrokerError> {
diff --git a/crates/agentkeys-broker-server/src/handlers/mod.rs b/crates/agentkeys-broker-server/src/handlers/mod.rs
index 30f8c12d..e4e89df6 100644
--- a/crates/agentkeys-broker-server/src/handlers/mod.rs
+++ b/crates/agentkeys-broker-server/src/handlers/mod.rs
@@ -1,3 +1,4 @@
+pub mod agent;
 pub mod auth;
 pub mod broker_status;
 pub mod cap;
diff --git a/crates/agentkeys-broker-server/src/handlers/oidc.rs b/crates/agentkeys-broker-server/src/handlers/oidc.rs
index c6a39e0d..321cad17 100644
--- a/crates/agentkeys-broker-server/src/handlers/oidc.rs
+++ b/crates/agentkeys-broker-server/src/handlers/oidc.rs
@@ -95,11 +95,25 @@ pub async fn mint_oidc_jwt(
             }
         };
 
+    // The actor_omni is read VERBATIM from the verified (broker-signed) session
+    // claim — never re-derived from a wallet (issue #144). A J1_agent has no
+    // wallet, so re-deriving would yield an empty/garbage tag → STS creds scoped
+    // to the wrong prefix → worker 403. For wallet/master sessions the claim
+    // equals the old re-derived value, so this is byte-identical for them.
     let wallet = session_claims.agentkeys.wallet_address;
-    tracing::Span::current().record("wallet", wallet.as_str());
+    let actor_omni = session_claims.agentkeys.omni_account;
+    // Report id for audit/span/response: the wallet for master sessions, the
+    // actor_omni for agents (no wallet). Drives the STS session name downstream.
+    let report_id = if wallet.is_empty() {
+        actor_omni.clone()
+    } else {
+        wallet.clone()
+    };
+    tracing::Span::current().record("wallet", report_id.as_str());
 
     let (claims, _now, exp) = build_oidc_jwt_claims(
         &state.config.oidc_issuer,
+        &actor_omni,
         &wallet,
         state.config.oidc_jwt_ttl_seconds,
     );
@@ -109,7 +123,7 @@ pub async fn mint_oidc_jwt(
     state.audit.record_mint(
         MintRecord {
             requester_token: token,
-            requester_wallet: &wallet,
+            requester_wallet: &report_id,
             requested_role: "oidc_jwt",
             session_duration_seconds: state.config.oidc_jwt_ttl_seconds as i32,
             sts_session_name: &state.oidc.kid,
@@ -121,7 +135,7 @@ pub async fn mint_oidc_jwt(
 
     Ok(Json(MintOidcJwtResponse {
         jwt,
-        wallet,
+        wallet: report_id,
         expiration: exp,
     }))
 }
@@ -156,6 +170,7 @@ pub async fn mint_oidc_jwt(
 /// v1 can be retired from the claim set.
 pub(crate) fn build_oidc_jwt_claims(
     issuer: &str,
+    actor_omni: &str,
     wallet: &str,
     ttl_seconds: u64,
 ) -> (serde_json::Value, i64, i64) {
@@ -165,24 +180,30 @@ pub(crate) fn build_oidc_jwt_claims(
         .unwrap_or(0);
     let exp = now + ttl_seconds as i64;
     let wallet_lc = wallet.to_lowercase();
-    // v2 actor_omni = SHA256("agentkeys" || "evm" || wallet_lc). Lives in
-    // `crate::identity::omni_account::derive_omni_account` so the broker
-    // never reimplements the hash — same function the storage layer uses
-    // when keying identity-link rows on omni.
-    let actor_omni =
-        crate::identity::omni_account::derive_omni_account("evm", &wallet_lc).to_string();
+    // `actor_omni` is supplied VERBATIM from the verified session claim (issue
+    // #144) — the broker signed it at session-mint time, so it's trusted and is
+    // NOT re-derived here. For a wallet/master session it equals
+    // SHA256("agentkeys"||"evm"||wallet_lc) (what the old code computed); for an
+    // agent J1 it is the HDKD child omni. The v1 `agentkeys_user_wallet` tag
+    // falls back to the actor_omni when there's no wallet so it's never empty
+    // (a v1 policy keyed on it then resolves to the same `bots/<actor>/` prefix).
+    let user_wallet = if wallet_lc.is_empty() {
+        actor_omni
+    } else {
+        wallet_lc.as_str()
+    };
 
     let claims = json!({
         "iss": issuer,
-        "sub": format!("agentkeys:agent:{}", wallet_lc),
+        "sub": format!("agentkeys:agent:{}", user_wallet),
         "aud": "sts.amazonaws.com",
         "iat": now,
         "exp": exp,
-        "agentkeys_user_wallet": wallet_lc,
+        "agentkeys_user_wallet": user_wallet,
         "agentkeys_actor_omni": actor_omni,
         "https://aws.amazon.com/tags": {
             "principal_tags": {
-                "agentkeys_user_wallet": [wallet_lc],
+                "agentkeys_user_wallet": [user_wallet],
                 "agentkeys_actor_omni": [actor_omni],
             },
             "transitive_tag_keys": [
@@ -194,3 +215,40 @@ pub(crate) fn build_oidc_jwt_claims(
 
     (claims, now, exp)
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::identity::omni_account::derive_omni_account;
+
+    #[test]
+    fn wallet_session_oidc_tags_unchanged_after_144() {
+        // Regression: for a wallet/master session the actor_omni read from the
+        // claim EQUALS the value the old code re-derived from the wallet, so the
+        // OIDC tag set is byte-identical to pre-#144.
+        let wallet = "0xAbCdEf0123456789abcdef0123456789ABCDef00";
+        let wallet_lc = wallet.to_lowercase();
+        let actor_omni = derive_omni_account("evm", &wallet_lc).to_string();
+        let (claims, _n, _e) = build_oidc_jwt_claims("https://issuer", &actor_omni, wallet, 300);
+        assert_eq!(claims["agentkeys_actor_omni"], actor_omni);
+        assert_eq!(claims["agentkeys_user_wallet"], wallet_lc);
+        assert_eq!(claims["sub"], format!("agentkeys:agent:{wallet_lc}"));
+        let tags = &claims["https://aws.amazon.com/tags"]["principal_tags"];
+        assert_eq!(tags["agentkeys_actor_omni"][0], actor_omni);
+        assert_eq!(tags["agentkeys_user_wallet"][0], wallet_lc);
+    }
+
+    #[test]
+    fn agent_session_tags_carry_hdkd_omni_and_no_empty_wallet() {
+        // Agent J1: HDKD child omni, empty wallet → the actor tag IS the HDKD
+        // omni (so STS scopes creds to bots/<child>/...), and the v1 user_wallet
+        // tag falls back to the omni rather than being empty.
+        let child = "a".repeat(64);
+        let (claims, _n, _e) = build_oidc_jwt_claims("https://issuer", &child, "", 300);
+        assert_eq!(claims["agentkeys_actor_omni"], child);
+        assert_eq!(claims["agentkeys_user_wallet"], child);
+        assert_eq!(claims["sub"], format!("agentkeys:agent:{child}"));
+        let tags = &claims["https://aws.amazon.com/tags"]["principal_tags"];
+        assert_eq!(tags["agentkeys_actor_omni"][0], child);
+    }
+}
diff --git a/crates/agentkeys-broker-server/src/jwt/issue.rs b/crates/agentkeys-broker-server/src/jwt/issue.rs
index 1b541847..4704fa70 100644
--- a/crates/agentkeys-broker-server/src/jwt/issue.rs
+++ b/crates/agentkeys-broker-server/src/jwt/issue.rs
@@ -62,6 +62,50 @@ pub fn mint_session_jwt(
     keypair.sign_jwt(&claims)
 }
 
+/// Mint `J1_agent` — the agent session JWT for the §10.2 link-code bootstrap
+/// (issue #144). Unlike `mint_session_jwt`, the actor omni is the **HDKD child**
+/// (decoupled from any wallet — `wallet_address` is empty), and the claim
+/// carries the agent lineage (`parent_omni`, `derivation_path`, `device_pubkey`).
+/// `identity_type` is `"agent_hdkd"` and `identity_value` is the K10 device
+/// address. The `omni_account` is the un-prefixed 64-hex child omni so it
+/// matches the PrincipalTag + S3-prefix shape downstream.
+#[allow(clippy::too_many_arguments)]
+pub fn mint_agent_session_jwt(
+    keypair: &SessionKeypair,
+    issuer: &str,
+    child_omni: &str,
+    parent_omni: &str,
+    derivation_path: &str,
+    device_pubkey: &str,
+    ttl_seconds: u64,
+) -> BrokerResult<String> {
+    let now = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map_err(|e| BrokerError::Internal(format!("clock before unix epoch: {e}")))?
+        .as_secs();
+    let exp = now + ttl_seconds;
+
+    let claims = json!({
+        "iss": issuer,
+        "sub": format!("agentkeys:agent:{}", child_omni),
+        "aud": "agentkeys:broker",
+        "exp": exp,
+        "iat": now,
+        "jti": ulid_like(),
+        "agentkeys": {
+            "omni_account":    child_omni,
+            "wallet_address":  "",
+            "identity_type":   "agent_hdkd",
+            "identity_value":  device_pubkey,
+            "parent_omni":     parent_omni,
+            "derivation_path": derivation_path,
+            "device_pubkey":   device_pubkey,
+        }
+    });
+
+    keypair.sign_jwt(&claims)
+}
+
 /// Mint an `audit_proof` JWT for a capability grant (Phase B, US-025).
 ///
 /// Per plan §3.5.5: the audit_proof is the broker's ES256 signature
diff --git a/crates/agentkeys-broker-server/src/jwt/verify.rs b/crates/agentkeys-broker-server/src/jwt/verify.rs
index 0fe38b39..1f1e1586 100644
--- a/crates/agentkeys-broker-server/src/jwt/verify.rs
+++ b/crates/agentkeys-broker-server/src/jwt/verify.rs
@@ -25,12 +25,26 @@ pub struct SessionClaims {
 }
 
 /// The custom `agentkeys` namespace inside the session JWT.
+///
+/// The `parent_omni` / `derivation_path` / `device_pubkey` fields are present
+/// only on agent sessions (`J1_agent`, issue #144). They are `Option` with
+/// `serde(default)` so existing wallet/master tokens (which never carried them)
+/// still deserialize — the change is purely additive.
 #[derive(Clone, Debug, Serialize, Deserialize)]
 pub struct AgentKeysClaims {
     pub omni_account: String,
     pub wallet_address: String,
     pub identity_type: String,
     pub identity_value: String,
+    /// Agent only: the parent (master) omni this child was HDKD-derived from.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub parent_omni: Option<String>,
+    /// Agent only: the HDKD path, e.g. `"//agent-a"`.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub derivation_path: Option<String>,
+    /// Agent only: the K10 device address whose pop_sig redeemed the link code.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub device_pubkey: Option<String>,
 }
 
 /// Verify a session JWT against the broker's session keypair. Validates
diff --git a/crates/agentkeys-broker-server/src/lib.rs b/crates/agentkeys-broker-server/src/lib.rs
index dcc92e00..6dae7864 100644
--- a/crates/agentkeys-broker-server/src/lib.rs
+++ b/crates/agentkeys-broker-server/src/lib.rs
@@ -62,6 +62,21 @@ pub fn create_router(state: SharedState) -> Router {
             "/v1/auth/wallet/verify",
             post(handlers::auth::wallet_verify::wallet_verify),
         )
+        // §10.2 agent-bootstrap link-code ceremony (issue #144). Master mints a
+        // code bound to the HDKD child omni; the agent redeems it (proving K10
+        // possession) → J1_agent; the master pulls pending bindings to approve.
+        .route(
+            "/v1/agent/create",
+            post(handlers::agent::create::agent_create),
+        )
+        .route(
+            "/v1/auth/link-code/redeem",
+            post(handlers::agent::redeem::link_code_redeem),
+        )
+        .route(
+            "/v1/agent/pending-bindings",
+            get(handlers::agent::pending::pending_bindings),
+        )
         // Phase B grant endpoints (US-026).
         .route(
             "/v1/grant/create",
diff --git a/crates/agentkeys-broker-server/src/main.rs b/crates/agentkeys-broker-server/src/main.rs
index 212a4c35..a5c95974 100644
--- a/crates/agentkeys-broker-server/src/main.rs
+++ b/crates/agentkeys-broker-server/src/main.rs
@@ -177,6 +177,7 @@ async fn main() -> anyhow::Result<()> {
         nonce_store: boot_artifacts.nonce_store,
         grant_store: boot_artifacts.grant_store,
         identity_link_store: boot_artifacts.identity_link_store,
+        link_code_store: boot_artifacts.link_code_store,
         metrics: Arc::new(agentkeys_broker_server::metrics::Metrics::new()),
         tier2: Arc::clone(&tier2),
         #[cfg(feature = "auth-email-link")]
diff --git a/crates/agentkeys-broker-server/src/state.rs b/crates/agentkeys-broker-server/src/state.rs
index 878d6e8f..4e8e8122 100644
--- a/crates/agentkeys-broker-server/src/state.rs
+++ b/crates/agentkeys-broker-server/src/state.rs
@@ -7,7 +7,7 @@ use crate::metrics::Metrics;
 use crate::oidc::OidcKeypair;
 use crate::plugins::audit::AuditPolicy;
 use crate::plugins::PluginRegistry;
-use crate::storage::{AuthNonceStore, GrantStore, IdentityLinkStore, WalletStore};
+use crate::storage::{AuthNonceStore, GrantStore, IdentityLinkStore, LinkCodeStore, WalletStore};
 use crate::sts::StsClient;
 
 /// Tier-2 reachability state shared with the /readyz handler.
@@ -43,6 +43,12 @@ pub struct AppState {
     /// (issue #72); grants are kept in-tree for master-managed audit and
     /// potential future re-introduction at the JWT-mint site.
     pub grant_store: Arc<GrantStore>,
+    /// §10.2 agent-bootstrap link codes + pending-binding records (issue #144).
+    /// `/v1/agent/create` issues a code bound to the HDKD child omni;
+    /// `/v1/auth/link-code/redeem` consumes it (capturing device_pubkey +
+    /// pop_sig) and mints `J1_agent`; `/v1/agent/pending-bindings` lets the
+    /// master pull redeemed-but-unbound rows to approve.
+    pub link_code_store: Arc<LinkCodeStore>,
     /// Identity links (Phase B, US-028). Maps verified identities
     /// (email, oauth2 sub, secondary EVM wallet) to their owning master
     /// OmniAccount. Recovery flow consults this to find which master
diff --git a/crates/agentkeys-broker-server/src/storage/link_codes.rs b/crates/agentkeys-broker-server/src/storage/link_codes.rs
new file mode 100644
index 00000000..bda4705b
--- /dev/null
+++ b/crates/agentkeys-broker-server/src/storage/link_codes.rs
@@ -0,0 +1,413 @@
+//! `LinkCodeStore` — the §10.2 agent-bootstrap link code + pending-binding
+//! record (issue #144).
+//!
+//! One row models the full pairing lifecycle:
+//!
+//! ```text
+//! issued      (master ran /v1/agent/create — code bound to a child omni)
+//!   → consumed (agent redeemed at /v1/auth/link-code/redeem — device_pubkey +
+//!               pop_sig captured; J1_agent minted)
+//!   → bound     (master pulled the pending binding + submitted registerAgentDevice)
+//! ```
+//!
+//! So this store doubles as the **pending-binding** record the master pulls
+//! (the substrate behind the production push notification): a `consumed` row
+//! that is not yet `bound` is "agent-A wants to pair + wants `[requested_scope]`".
+//!
+//! SQLite (not in-memory) because the broker restarts between demo phases; an
+//! in-memory store would silently drop codes and produce confusing redeem-404s.
+//! Mirrors the single-use / TTL / race-safety posture of `oauth_pending.rs`
+//! (atomic `UPDATE ... WHERE consumed_at IS NULL`), but returns `BrokerError`
+//! since it's consumed by broker handlers (not the auth-plugin layer).
+
+use std::path::Path;
+use std::sync::{Mutex, MutexGuard};
+
+use rusqlite::{params, Connection, OptionalExtension};
+
+use crate::error::{BrokerError, BrokerResult};
+
+/// Link-code TTL — the window in which an agent must redeem (arch.md §10.2).
+pub const LINK_CODE_TTL_SECONDS: i64 = 600;
+
+/// SQLite-backed link-code + pending-binding store.
+pub struct LinkCodeStore {
+    conn: Mutex<Connection>,
+}
+
+/// Outcome of [`LinkCodeStore::consume`].
+#[derive(Debug, PartialEq, Eq)]
+pub enum LinkCodeConsume {
+    /// Code was unused + unexpired; consume succeeded. Carries the values the
+    /// redeem handler needs to mint `J1_agent`.
+    Available {
+        child_omni: String,
+        operator_omni: String,
+        label: String,
+        requested_scope: String,
+    },
+    /// Code never existed or was already redeemed (collapsed to one variant so
+    /// a prober can't distinguish — same posture as the OAuth2/email stores).
+    NotFoundOrConsumed,
+    /// Code existed + unused but past its TTL.
+    Expired,
+}
+
+/// A redeemed-but-not-yet-bound row — what the master pulls from
+/// `GET /v1/agent/pending-bindings` to approve.
+#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)]
+pub struct PendingBinding {
+    pub link_code: String,
+    pub child_omni: String,
+    pub operator_omni: String,
+    pub label: String,
+    pub requested_scope: String,
+    pub device_pubkey: String,
+    pub pop_sig: String,
+}
+
+impl LinkCodeStore {
+    pub fn open(path: &Path) -> BrokerResult<Self> {
+        if let Some(parent) = path.parent() {
+            std::fs::create_dir_all(parent)
+                .map_err(|e| BrokerError::Internal(format!("create link_codes dir: {e}")))?;
+        }
+        let conn = Connection::open(path)
+            .map_err(|e| BrokerError::Internal(format!("open link_codes db: {e}")))?;
+        let store = Self {
+            conn: Mutex::new(conn),
+        };
+        store.init_schema()?;
+        Ok(store)
+    }
+
+    pub fn open_in_memory() -> BrokerResult<Self> {
+        let conn = Connection::open_in_memory()
+            .map_err(|e| BrokerError::Internal(format!("open in-memory link_codes db: {e}")))?;
+        let store = Self {
+            conn: Mutex::new(conn),
+        };
+        store.init_schema()?;
+        Ok(store)
+    }
+
+    fn lock(&self) -> BrokerResult<MutexGuard<'_, Connection>> {
+        self.conn
+            .lock()
+            .map_err(|e| BrokerError::Internal(format!("link_codes mutex poisoned: {e}")))
+    }
+
+    fn init_schema(&self) -> BrokerResult<()> {
+        let conn = self.lock()?;
+        conn.execute_batch(
+            "PRAGMA journal_mode=WAL;
+             PRAGMA synchronous=NORMAL;
+             CREATE TABLE IF NOT EXISTS link_codes (
+                link_code       TEXT PRIMARY KEY,
+                child_omni      TEXT NOT NULL,
+                operator_omni   TEXT NOT NULL,
+                label           TEXT NOT NULL,
+                requested_scope TEXT NOT NULL,
+                issued_at       INTEGER NOT NULL,
+                expires_at      INTEGER NOT NULL,
+                consumed_at     INTEGER,
+                device_pubkey   TEXT,
+                pop_sig         TEXT,
+                bound_at        INTEGER
+             );
+             CREATE INDEX IF NOT EXISTS idx_link_codes_operator
+                ON link_codes(operator_omni);
+             CREATE INDEX IF NOT EXISTS idx_link_codes_expires_at
+                ON link_codes(expires_at);",
+        )
+        .map_err(|e| BrokerError::Internal(format!("init link_codes schema: {e}")))?;
+        Ok(())
+    }
+
+    /// Mint a new link code bound to a child omni (master ran `/v1/agent/create`).
+    #[allow(clippy::too_many_arguments)]
+    pub fn issue(
+        &self,
+        link_code: &str,
+        child_omni: &str,
+        operator_omni: &str,
+        label: &str,
+        requested_scope: &str,
+        issued_at: i64,
+        expires_at: i64,
+    ) -> BrokerResult<()> {
+        let conn = self.lock()?;
+        conn.execute(
+            "INSERT INTO link_codes
+                (link_code, child_omni, operator_omni, label, requested_scope, issued_at, expires_at)
+             VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7)",
+            params![
+                link_code,
+                child_omni,
+                operator_omni,
+                label,
+                requested_scope,
+                issued_at,
+                expires_at
+            ],
+        )
+        .map_err(|e| BrokerError::Internal(format!("insert link_code: {e}")))?;
+        Ok(())
+    }
+
+    /// Atomically redeem the code, persisting `device_pubkey` + `pop_sig` onto
+    /// the row (state → consumed/pending-binding). Race-safe via the conditional
+    /// `UPDATE ... WHERE consumed_at IS NULL`.
+    pub fn consume(
+        &self,
+        link_code: &str,
+        device_pubkey: &str,
+        pop_sig: &str,
+        now: i64,
+    ) -> BrokerResult<LinkCodeConsume> {
+        let conn = self.lock()?;
+        let peek: Option<(String, String, String, i64, Option<i64>)> = conn
+            .query_row(
+                "SELECT child_omni, operator_omni, label, expires_at, consumed_at
+                 FROM link_codes WHERE link_code = ?1",
+                params![link_code],
+                |row| {
+                    Ok((
+                        row.get(0)?,
+                        row.get(1)?,
+                        row.get(2)?,
+                        row.get(3)?,
+                        row.get(4)?,
+                    ))
+                },
+            )
+            .optional()
+            .map_err(|e| BrokerError::Internal(format!("peek link_code: {e}")))?;
+
+        let (child_omni, operator_omni, label, expires_at, consumed_at) = match peek {
+            None => return Ok(LinkCodeConsume::NotFoundOrConsumed),
+            Some(t) => t,
+        };
+        if consumed_at.is_some() {
+            return Ok(LinkCodeConsume::NotFoundOrConsumed);
+        }
+        if expires_at < now {
+            return Ok(LinkCodeConsume::Expired);
+        }
+        let requested_scope: String = conn
+            .query_row(
+                "SELECT requested_scope FROM link_codes WHERE link_code = ?1",
+                params![link_code],
+                |row| row.get(0),
+            )
+            .map_err(|e| BrokerError::Internal(format!("read requested_scope: {e}")))?;
+        let rows = conn
+            .execute(
+                "UPDATE link_codes
+                 SET consumed_at = ?1, device_pubkey = ?2, pop_sig = ?3
+                 WHERE link_code = ?4 AND consumed_at IS NULL",
+                params![now, device_pubkey, pop_sig, link_code],
+            )
+            .map_err(|e| BrokerError::Internal(format!("update link_code: {e}")))?;
+        if rows == 0 {
+            // Lost the race to a concurrent redeem.
+            Ok(LinkCodeConsume::NotFoundOrConsumed)
+        } else {
+            Ok(LinkCodeConsume::Available {
+                child_omni,
+                operator_omni,
+                label,
+                requested_scope,
+            })
+        }
+    }
+
+    /// Rows that have been redeemed but not yet bound on-chain, for one operator
+    /// — the master's pending-approval queue. Returns oldest-first.
+    pub fn pending_bindings(&self, operator_omni: &str) -> BrokerResult<Vec<PendingBinding>> {
+        let conn = self.lock()?;
+        let mut stmt = conn
+            .prepare(
+                "SELECT link_code, child_omni, operator_omni, label, requested_scope,
+                        device_pubkey, pop_sig
+                 FROM link_codes
+                 WHERE operator_omni = ?1 AND consumed_at IS NOT NULL AND bound_at IS NULL
+                 ORDER BY consumed_at ASC",
+            )
+            .map_err(|e| BrokerError::Internal(format!("prepare pending_bindings: {e}")))?;
+        let rows = stmt
+            .query_map(params![operator_omni], |row| {
+                Ok(PendingBinding {
+                    link_code: row.get(0)?,
+                    child_omni: row.get(1)?,
+                    operator_omni: row.get(2)?,
+                    label: row.get(3)?,
+                    requested_scope: row.get(4)?,
+                    device_pubkey: row.get(5)?,
+                    pop_sig: row.get(6)?,
+                })
+            })
+            .map_err(|e| BrokerError::Internal(format!("query pending_bindings: {e}")))?;
+        let mut out = Vec::new();
+        for r in rows {
+            out.push(r.map_err(|e| BrokerError::Internal(format!("row pending_bindings: {e}")))?);
+        }
+        Ok(out)
+    }
+
+    /// Mark a redeemed row as bound (master acked the on-chain submit). Idempotent
+    /// — a second ack is a no-op. Returns the matched/updated row count.
+    pub fn mark_bound(&self, link_code: &str, now: i64) -> BrokerResult<usize> {
+        let conn = self.lock()?;
+        let n = conn
+            .execute(
+                "UPDATE link_codes SET bound_at = ?1
+                 WHERE link_code = ?2 AND consumed_at IS NOT NULL AND bound_at IS NULL",
+                params![now, link_code],
+            )
+            .map_err(|e| BrokerError::Internal(format!("mark_bound link_code: {e}")))?;
+        Ok(n)
+    }
+
+    /// Janitor — DELETE expired codes that were never redeemed. Consumed rows are
+    /// kept (the master may still need to bind them — a binding doesn't expire).
+    pub fn purge_expired(&self, now: i64, retention_seconds: i64) -> BrokerResult<usize> {
+        let conn = self.lock()?;
+        let cutoff = now - retention_seconds;
+        let n = conn
+            .execute(
+                "DELETE FROM link_codes WHERE expires_at < ?1 AND consumed_at IS NULL",
+                params![cutoff],
+            )
+            .map_err(|e| BrokerError::Internal(format!("purge link_codes: {e}")))?;
+        Ok(n)
+    }
+
+    /// Writability probe for `/readyz`.
+    pub fn writable(&self) -> bool {
+        let Ok(conn) = self.conn.lock() else {
+            return false;
+        };
+        conn.execute(
+            "CREATE TABLE IF NOT EXISTS _readyz_probe (id INTEGER PRIMARY KEY)",
+            [],
+        )
+        .is_ok()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn store() -> LinkCodeStore {
+        LinkCodeStore::open_in_memory().unwrap()
+    }
+
+    #[test]
+    fn issue_then_consume_round_trip() {
+        let s = store();
+        s.issue("lc-1", "child", "op", "agent-a", "memory", 100, 700)
+            .unwrap();
+        let out = s.consume("lc-1", "0xdev", "0xpop", 200).unwrap();
+        assert_eq!(
+            out,
+            LinkCodeConsume::Available {
+                child_omni: "child".into(),
+                operator_omni: "op".into(),
+                label: "agent-a".into(),
+                requested_scope: "memory".into(),
+            }
+        );
+    }
+
+    #[test]
+    fn second_redeem_is_rejected() {
+        let s = store();
+        s.issue("lc-1", "child", "op", "agent-a", "memory", 100, 700)
+            .unwrap();
+        let _ = s.consume("lc-1", "0xdev", "0xpop", 200).unwrap();
+        let replay = s.consume("lc-1", "0xdev", "0xpop", 250).unwrap();
+        assert_eq!(replay, LinkCodeConsume::NotFoundOrConsumed);
+    }
+
+    #[test]
+    fn expired_code_is_not_consumable() {
+        let s = store();
+        s.issue("lc-1", "child", "op", "agent-a", "memory", 100, 200)
+            .unwrap();
+        assert_eq!(
+            s.consume("lc-1", "0xdev", "0xpop", 9999).unwrap(),
+            LinkCodeConsume::Expired
+        );
+    }
+
+    #[test]
+    fn unknown_code_is_not_found() {
+        let s = store();
+        assert_eq!(
+            s.consume("nope", "0xdev", "0xpop", 100).unwrap(),
+            LinkCodeConsume::NotFoundOrConsumed
+        );
+    }
+
+    #[test]
+    fn pending_bindings_returns_consumed_unbound_rows() {
+        let s = store();
+        s.issue("lc-1", "childA", "op", "agent-a", "memory", 100, 700)
+            .unwrap();
+        s.issue("lc-2", "childB", "op-other", "agent-b", "memory", 100, 700)
+            .unwrap();
+        // Not redeemed yet → no pending binding.
+        assert!(s.pending_bindings("op").unwrap().is_empty());
+        s.consume("lc-1", "0xdevA", "0xpopA", 200).unwrap();
+        let pend = s.pending_bindings("op").unwrap();
+        assert_eq!(pend.len(), 1);
+        assert_eq!(pend[0].child_omni, "childA");
+        assert_eq!(pend[0].device_pubkey, "0xdevA");
+        assert_eq!(pend[0].pop_sig, "0xpopA");
+        // Different operator's redemption doesn't leak.
+        assert!(s
+            .pending_bindings("op")
+            .unwrap()
+            .iter()
+            .all(|b| b.operator_omni == "op"));
+    }
+
+    #[test]
+    fn mark_bound_clears_from_pending() {
+        let s = store();
+        s.issue("lc-1", "childA", "op", "agent-a", "memory", 100, 700)
+            .unwrap();
+        s.consume("lc-1", "0xdevA", "0xpopA", 200).unwrap();
+        assert_eq!(s.pending_bindings("op").unwrap().len(), 1);
+        assert_eq!(s.mark_bound("lc-1", 300).unwrap(), 1);
+        assert!(s.pending_bindings("op").unwrap().is_empty());
+        // Idempotent: a second ack matches nothing.
+        assert_eq!(s.mark_bound("lc-1", 400).unwrap(), 0);
+    }
+
+    #[test]
+    fn purge_drops_unredeemed_expired_keeps_pending() {
+        let s = store();
+        s.issue("stale", "childA", "op", "agent-a", "memory", 50, 100)
+            .unwrap();
+        s.issue("redeemed", "childB", "op", "agent-b", "memory", 50, 100)
+            .unwrap();
+        s.consume("redeemed", "0xdevB", "0xpopB", 60).unwrap();
+        let n = s.purge_expired(10_000, 100).unwrap();
+        assert_eq!(n, 1); // only the unredeemed-expired "stale" row
+                          // The redeemed row survives as a pending binding.
+        assert_eq!(s.pending_bindings("op").unwrap().len(), 1);
+    }
+
+    #[test]
+    fn issue_rejects_duplicate_code() {
+        let s = store();
+        s.issue("dup", "c", "op", "agent-a", "memory", 100, 700)
+            .unwrap();
+        assert!(s
+            .issue("dup", "c", "op", "agent-a", "memory", 100, 700)
+            .is_err());
+    }
+}
diff --git a/crates/agentkeys-broker-server/src/storage/mod.rs b/crates/agentkeys-broker-server/src/storage/mod.rs
index 4d2087f3..e0ffa60b 100644
--- a/crates/agentkeys-broker-server/src/storage/mod.rs
+++ b/crates/agentkeys-broker-server/src/storage/mod.rs
@@ -16,6 +16,9 @@ pub mod email_rate_limits;
 pub mod email_tokens;
 pub mod grants;
 pub mod identity_links;
+// Issue #144 — §10.2 agent-bootstrap link codes + pending-binding records.
+// Unconditional (the agent bootstrap is core, not feature-gated).
+pub mod link_codes;
 #[cfg(feature = "auth-oauth2")]
 pub mod oauth_pending;
 #[cfg(any(feature = "auth-email-link", feature = "auth-oauth2"))]
@@ -29,6 +32,7 @@ pub use email_rate_limits::{EmailRateLimitStore, RateLimitOutcome};
 pub use email_tokens::{EmailConsumeOutcome, EmailRequestStatus, EmailTokenStore};
 pub use grants::{Grant, GrantConsumeOutcome, GrantStore};
 pub use identity_links::{IdentityLink, IdentityLinkStore};
+pub use link_codes::{LinkCodeConsume, LinkCodeStore, PendingBinding, LINK_CODE_TTL_SECONDS};
 #[cfg(feature = "auth-oauth2")]
 pub use oauth_pending::{OAuth2PendingConsume, OAuth2PendingStatus, OAuth2PendingStore};
 #[cfg(any(feature = "auth-email-link", feature = "auth-oauth2"))]
diff --git a/crates/agentkeys-broker-server/tests/agent_bootstrap_flow.rs b/crates/agentkeys-broker-server/tests/agent_bootstrap_flow.rs
new file mode 100644
index 00000000..6b8fad14
--- /dev/null
+++ b/crates/agentkeys-broker-server/tests/agent_bootstrap_flow.rs
@@ -0,0 +1,300 @@
+//! End-to-end tests for the §10.2 agent-bootstrap link-code ceremony (issue #144):
+//!   create (master, J1-gated) → redeem (agent, pop_sig) → pending-bindings (master).
+//!
+//! Exercises the full HTTP path through `create_router`, including the real
+//! secp256k1 pop_sig produced by `agentkeys_core::device_crypto::DeviceKey` and
+//! verified by the broker's redeem handler — the redeem-critical match.
+
+use std::path::PathBuf;
+use std::sync::Arc;
+
+use agentkeys_broker_server::audit::AuditLog;
+use agentkeys_broker_server::config::BrokerConfig;
+use agentkeys_broker_server::create_router;
+use agentkeys_broker_server::identity::derive_omni_account;
+use agentkeys_broker_server::jwt::issue::mint_session_jwt;
+use agentkeys_broker_server::jwt::verify::verify_session_jwt;
+use agentkeys_broker_server::oidc::OidcKeypair;
+use agentkeys_broker_server::state::AppState;
+use agentkeys_broker_server::sts::{AssumedCredentials, StsClient, StubStsClient};
+use agentkeys_core::device_crypto::DeviceKey;
+use serde_json::{json, Value};
+use tempfile::TempDir;
+
+const TEST_ISSUER: &str = "https://oidc.test.invalid";
+
+fn stub_creds() -> AssumedCredentials {
+    AssumedCredentials {
+        access_key_id: "ASIA-stub".into(),
+        secret_access_key: "stub".into(),
+        session_token: "stub".into(),
+        expiration_unix: 9_999_999_999,
+    }
+}
+
+async fn spawn_broker() -> (String, Arc<AppState>) {
+    let tmp = Box::leak(Box::new(TempDir::new().unwrap()));
+    let keypair_path = tmp.path().join("oidc-keypair.json");
+    let oidc = OidcKeypair::generate_and_persist(&keypair_path).unwrap();
+    let sts: Arc<dyn StsClient> = Arc::new(StubStsClient::ok(stub_creds()));
+    let config = BrokerConfig {
+        data_role_arn: "arn:aws:iam::000:role/test".into(),
+        audit_db_path: PathBuf::from(":memory:"),
+        aws_region: "us-east-1".into(),
+        session_duration_seconds: 3600,
+        shutdown_grace_seconds: 5,
+        oidc_issuer: TEST_ISSUER.into(),
+        oidc_keypair_path: keypair_path,
+        oidc_jwt_ttl_seconds: 300,
+    };
+    let http = reqwest::Client::builder()
+        .timeout(std::time::Duration::from_secs(2))
+        .build()
+        .unwrap();
+    let session_keypair = agentkeys_broker_server::jwt::SessionKeypair::generate_and_persist(
+        &tmp.path().join("session-keypair.json"),
+    )
+    .unwrap();
+    let wallet_store =
+        Arc::new(agentkeys_broker_server::storage::WalletStore::open_in_memory().unwrap());
+    let nonce_store =
+        Arc::new(agentkeys_broker_server::storage::AuthNonceStore::open_in_memory().unwrap());
+    let sqlite_anchor: Arc<dyn agentkeys_broker_server::plugins::audit::AuditAnchor> = Arc::new(
+        agentkeys_broker_server::plugins::audit::sqlite::SqliteAnchor::open_in_memory().unwrap(),
+    );
+    let registry = Arc::new(agentkeys_broker_server::plugins::PluginRegistry {
+        auth: std::collections::HashMap::new(),
+        wallet: Arc::new(
+            agentkeys_broker_server::plugins::wallet::keystore::ClientSideKeystoreProvisioner::new(
+                Arc::clone(&wallet_store),
+            ),
+        ),
+        audit: vec![sqlite_anchor],
+    });
+    let state = Arc::new(AppState {
+        config,
+        http,
+        audit: AuditLog::open_in_memory().unwrap(),
+        sts,
+        oidc: Arc::new(oidc),
+        session_keypair: Arc::new(session_keypair),
+        registry,
+        audit_policy: agentkeys_broker_server::plugins::audit::AuditPolicy::SqlitePrimary,
+        wallet_store,
+        nonce_store,
+        grant_store: Arc::new(
+            agentkeys_broker_server::storage::GrantStore::open_in_memory().unwrap(),
+        ),
+        identity_link_store: Arc::new(
+            agentkeys_broker_server::storage::IdentityLinkStore::open_in_memory().unwrap(),
+        ),
+        link_code_store: Arc::new(
+            agentkeys_broker_server::storage::LinkCodeStore::open_in_memory().unwrap(),
+        ),
+        metrics: Arc::new(agentkeys_broker_server::metrics::Metrics::new()),
+        tier2: Arc::new(agentkeys_broker_server::state::Tier2State::default()),
+        #[cfg(feature = "auth-email-link")]
+        email_link: None,
+        #[cfg(feature = "auth-oauth2")]
+        oauth2: None,
+    });
+    let app = create_router(state.clone());
+    let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+    let addr = listener.local_addr().unwrap();
+    tokio::spawn(async move {
+        axum::serve(listener, app).await.unwrap();
+    });
+    (format!("http://{}", addr), state)
+}
+
+/// Mint a master J1 session bound to a fresh master omni; returns (bearer, master_omni).
+fn master_session(state: &AppState) -> (String, String) {
+    let master_wallet = "0xabcdef0123456789abcdef0123456789abcdef01";
+    let master_omni = derive_omni_account("evm", master_wallet).to_string();
+    let token = mint_session_jwt(
+        &state.session_keypair,
+        TEST_ISSUER,
+        &master_omni,
+        master_wallet,
+        "evm",
+        master_wallet,
+        3600,
+    )
+    .unwrap();
+    (token, master_omni)
+}
+
+#[tokio::test]
+async fn create_requires_master_bearer() {
+    let (broker_url, _state) = spawn_broker().await;
+    let resp = reqwest::Client::new()
+        .post(format!("{}/v1/agent/create", broker_url))
+        .json(&json!({ "label": "agent-a" }))
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), reqwest::StatusCode::UNAUTHORIZED);
+}
+
+#[tokio::test]
+async fn create_rejects_bad_label() {
+    let (broker_url, state) = spawn_broker().await;
+    let (bearer, _) = master_session(&state);
+    let resp = reqwest::Client::new()
+        .post(format!("{}/v1/agent/create", broker_url))
+        .header("Authorization", format!("Bearer {bearer}"))
+        .json(&json!({ "label": "Agent/A" }))
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), reqwest::StatusCode::BAD_REQUEST);
+}
+
+#[tokio::test]
+async fn full_create_redeem_pending_flow() {
+    let (broker_url, state) = spawn_broker().await;
+    let (bearer, master_omni) = master_session(&state);
+    let client = reqwest::Client::new();
+
+    // create → real broker link code + HDKD child omni.
+    let create: Value = client
+        .post(format!("{}/v1/agent/create", broker_url))
+        .header("Authorization", format!("Bearer {bearer}"))
+        .json(&json!({ "label": "agent-a", "requested_scope": "memory" }))
+        .send()
+        .await
+        .unwrap()
+        .json()
+        .await
+        .unwrap();
+    let link_code = create["link_code"].as_str().unwrap().to_string();
+    let child_omni = create["child_omni"].as_str().unwrap().to_string();
+    // Public recomputability (acceptance criterion).
+    assert_eq!(
+        child_omni,
+        agentkeys_core::actor_omni::child_omni_hex(&master_omni, "agent-a").unwrap()
+    );
+    assert_eq!(create["operator_omni"], master_omni);
+
+    // agent generates K10 in the sandbox + redeems with a real pop_sig.
+    let kd = TempDir::new().unwrap();
+    let dk =
+        DeviceKey::load_or_generate(kd.path().join("dev.key").to_str().unwrap(), true).unwrap();
+    let redeem: Value = client
+        .post(format!("{}/v1/auth/link-code/redeem", broker_url))
+        .json(&json!({
+            "link_code": link_code,
+            "device_pubkey": dk.address(),
+            "pop_sig": dk.pop_sig().unwrap(),
+        }))
+        .send()
+        .await
+        .unwrap()
+        .json()
+        .await
+        .unwrap();
+    let j1_agent = redeem["session_jwt"].as_str().unwrap();
+    assert_eq!(redeem["child_omni"], child_omni);
+
+    // J1_agent carries the HDKD omni + lineage.
+    let claims = verify_session_jwt(&state.session_keypair, TEST_ISSUER, j1_agent).unwrap();
+    assert_eq!(claims.agentkeys.omni_account, child_omni);
+    assert_eq!(
+        claims.agentkeys.parent_omni.as_deref(),
+        Some(master_omni.as_str())
+    );
+    assert_eq!(
+        claims.agentkeys.derivation_path.as_deref(),
+        Some("//agent-a")
+    );
+    assert_eq!(
+        claims.agentkeys.device_pubkey.as_deref(),
+        Some(dk.address())
+    );
+    assert_eq!(claims.agentkeys.identity_type, "agent_hdkd");
+
+    // master pulls the pending binding (the push-notification substrate).
+    let pending: Value = client
+        .get(format!("{}/v1/agent/pending-bindings", broker_url))
+        .header("Authorization", format!("Bearer {bearer}"))
+        .send()
+        .await
+        .unwrap()
+        .json()
+        .await
+        .unwrap();
+    let arr = pending["pending"].as_array().unwrap();
+    assert_eq!(arr.len(), 1);
+    assert_eq!(arr[0]["child_omni"], child_omni);
+    assert_eq!(arr[0]["device_pubkey"], dk.address());
+    assert_eq!(arr[0]["requested_scope"], "memory");
+    assert!(arr[0]["pop_sig"].as_str().unwrap().starts_with("0x"));
+    assert!(arr[0]["device_key_hash"]
+        .as_str()
+        .unwrap()
+        .starts_with("0x"));
+
+    // single-use: a second redeem of the same code is rejected.
+    let replay = client
+        .post(format!("{}/v1/auth/link-code/redeem", broker_url))
+        .json(&json!({
+            "link_code": link_code,
+            "device_pubkey": dk.address(),
+            "pop_sig": dk.pop_sig().unwrap(),
+        }))
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(replay.status(), reqwest::StatusCode::UNAUTHORIZED);
+}
+
+#[tokio::test]
+async fn bad_pop_sig_rejected_and_code_remains_redeemable() {
+    let (broker_url, state) = spawn_broker().await;
+    let (bearer, _master_omni) = master_session(&state);
+    let client = reqwest::Client::new();
+    let create: Value = client
+        .post(format!("{}/v1/agent/create", broker_url))
+        .header("Authorization", format!("Bearer {bearer}"))
+        .json(&json!({ "label": "agent-b" }))
+        .send()
+        .await
+        .unwrap()
+        .json()
+        .await
+        .unwrap();
+    let link_code = create["link_code"].as_str().unwrap().to_string();
+
+    let kd = TempDir::new().unwrap();
+    let dk =
+        DeviceKey::load_or_generate(kd.path().join("dev.key").to_str().unwrap(), true).unwrap();
+
+    // A pop_sig from a DIFFERENT key must not redeem (recovers to wrong address).
+    let other =
+        DeviceKey::load_or_generate(kd.path().join("other.key").to_str().unwrap(), true).unwrap();
+    let bad = client
+        .post(format!("{}/v1/auth/link-code/redeem", broker_url))
+        .json(&json!({
+            "link_code": link_code,
+            "device_pubkey": dk.address(),
+            "pop_sig": other.pop_sig().unwrap(),
+        }))
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(bad.status(), reqwest::StatusCode::UNAUTHORIZED);
+
+    // The single-use code was NOT burned by the failed attempt — a correct
+    // pop_sig still redeems (pop_sig verified BEFORE consume).
+    let good = client
+        .post(format!("{}/v1/auth/link-code/redeem", broker_url))
+        .json(&json!({
+            "link_code": link_code,
+            "device_pubkey": dk.address(),
+            "pop_sig": dk.pop_sig().unwrap(),
+        }))
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(good.status(), reqwest::StatusCode::OK);
+}
diff --git a/crates/agentkeys-broker-server/tests/auth_wallet_flow.rs b/crates/agentkeys-broker-server/tests/auth_wallet_flow.rs
index fe33f6fa..ae3e6e15 100644
--- a/crates/agentkeys-broker-server/tests/auth_wallet_flow.rs
+++ b/crates/agentkeys-broker-server/tests/auth_wallet_flow.rs
@@ -108,6 +108,9 @@ async fn spawn_broker_with_wallet_sig() -> (String, Arc<AppState>) {
         nonce_store,
         grant_store: Arc::new(GrantStore::open_in_memory().unwrap()),
         identity_link_store: Arc::new(IdentityLinkStore::open_in_memory().unwrap()),
+        link_code_store: Arc::new(
+            agentkeys_broker_server::storage::LinkCodeStore::open_in_memory().unwrap(),
+        ),
         metrics: Arc::new(agentkeys_broker_server::metrics::Metrics::new()),
         tier2: Arc::new(Tier2State::default()),
         #[cfg(feature = "auth-email-link")]
diff --git a/crates/agentkeys-broker-server/tests/email_flow.rs b/crates/agentkeys-broker-server/tests/email_flow.rs
index 4b98232b..568e5dfd 100644
--- a/crates/agentkeys-broker-server/tests/email_flow.rs
+++ b/crates/agentkeys-broker-server/tests/email_flow.rs
@@ -125,6 +125,9 @@ async fn spawn_broker() -> (String, Arc<AppState>, Arc<StubEmailSender>) {
         nonce_store,
         grant_store: Arc::new(GrantStore::open_in_memory().unwrap()),
         identity_link_store: Arc::new(IdentityLinkStore::open_in_memory().unwrap()),
+        link_code_store: Arc::new(
+            agentkeys_broker_server::storage::LinkCodeStore::open_in_memory().unwrap(),
+        ),
         metrics: Arc::new(agentkeys_broker_server::metrics::Metrics::new()),
         tier2: Arc::new(Tier2State::default()),
         email_link: Some(plugin.clone()),
diff --git a/crates/agentkeys-broker-server/tests/grant_flow.rs b/crates/agentkeys-broker-server/tests/grant_flow.rs
index 007eaf38..84542d5d 100644
--- a/crates/agentkeys-broker-server/tests/grant_flow.rs
+++ b/crates/agentkeys-broker-server/tests/grant_flow.rs
@@ -107,6 +107,9 @@ async fn spawn_broker() -> Harness {
         nonce_store,
         grant_store: Arc::new(GrantStore::open_in_memory().unwrap()),
         identity_link_store: Arc::new(IdentityLinkStore::open_in_memory().unwrap()),
+        link_code_store: Arc::new(
+            agentkeys_broker_server::storage::LinkCodeStore::open_in_memory().unwrap(),
+        ),
         metrics: Arc::new(agentkeys_broker_server::metrics::Metrics::new()),
         tier2: Arc::new(Tier2State::default()),
         #[cfg(feature = "auth-email-link")]
diff --git a/crates/agentkeys-broker-server/tests/oauth2_flow.rs b/crates/agentkeys-broker-server/tests/oauth2_flow.rs
index 09707cc3..1ab605f4 100644
--- a/crates/agentkeys-broker-server/tests/oauth2_flow.rs
+++ b/crates/agentkeys-broker-server/tests/oauth2_flow.rs
@@ -132,6 +132,9 @@ async fn spawn_broker() -> (String, Arc<AppState>, Arc<StubOAuth2Provider>) {
         nonce_store,
         grant_store: Arc::new(GrantStore::open_in_memory().unwrap()),
         identity_link_store: Arc::new(IdentityLinkStore::open_in_memory().unwrap()),
+        link_code_store: Arc::new(
+            agentkeys_broker_server::storage::LinkCodeStore::open_in_memory().unwrap(),
+        ),
         metrics: Arc::new(agentkeys_broker_server::metrics::Metrics::new()),
         tier2: Arc::new(Tier2State::default()),
         #[cfg(feature = "auth-email-link")]
diff --git a/crates/agentkeys-broker-server/tests/oidc_flow.rs b/crates/agentkeys-broker-server/tests/oidc_flow.rs
index 3ad980af..61e70d28 100644
--- a/crates/agentkeys-broker-server/tests/oidc_flow.rs
+++ b/crates/agentkeys-broker-server/tests/oidc_flow.rs
@@ -96,6 +96,9 @@ async fn spawn_broker() -> (String, Arc<AppState>) {
         nonce_store,
         grant_store: Arc::new(GrantStore::open_in_memory().unwrap()),
         identity_link_store: Arc::new(IdentityLinkStore::open_in_memory().unwrap()),
+        link_code_store: Arc::new(
+            agentkeys_broker_server::storage::LinkCodeStore::open_in_memory().unwrap(),
+        ),
         metrics: Arc::new(agentkeys_broker_server::metrics::Metrics::new()),
         tier2: std::sync::Arc::new(agentkeys_broker_server::state::Tier2State::default()),
         #[cfg(feature = "auth-email-link")]
diff --git a/crates/agentkeys-broker-server/tests/wallet_flow.rs b/crates/agentkeys-broker-server/tests/wallet_flow.rs
index 7c9c3603..00bfabfa 100644
--- a/crates/agentkeys-broker-server/tests/wallet_flow.rs
+++ b/crates/agentkeys-broker-server/tests/wallet_flow.rs
@@ -100,6 +100,9 @@ async fn spawn_broker() -> Harness {
         nonce_store,
         grant_store: Arc::new(GrantStore::open_in_memory().unwrap()),
         identity_link_store: Arc::new(IdentityLinkStore::open_in_memory().unwrap()),
+        link_code_store: Arc::new(
+            agentkeys_broker_server::storage::LinkCodeStore::open_in_memory().unwrap(),
+        ),
         metrics: Arc::new(agentkeys_broker_server::metrics::Metrics::new()),
         tier2: Arc::new(Tier2State::default()),
         #[cfg(feature = "auth-email-link")]
diff --git a/crates/agentkeys-cli/src/agent_admin.rs b/crates/agentkeys-cli/src/agent_admin.rs
new file mode 100644
index 00000000..aaeb0bd9
--- /dev/null
+++ b/crates/agentkeys-cli/src/agent_admin.rs
@@ -0,0 +1,80 @@
+//! Master-side §10.2 agent admin (issue #144): mint link codes + pull pending
+//! bindings. These are the master's half of the link-code ceremony — the agent
+//! half lives in the daemon's `--init-link-code` one-shot.
+//!
+//! Both commands are gated by the master's `J1` session bearer. The on-chain
+//! binding and scope grant (the "bind" and "grant" steps the operator approves
+//! with one Touch ID) stay in the chain helpers (`heima-agent-create.sh
+//! --from-pubkey` and `heima-scope-set.sh --webauthn`) because chain submission
+//! lives in shell + `cast`; those two helpers are the deterministic two-step
+//! split the test drives. `agent pending` is the production-flow rendezvous: the
+//! master discovers "agent-X wants to pair, wants `[scope]`" by pulling the broker.
+
+use anyhow::{anyhow, Context, Result};
+use serde_json::{json, Value};
+
+fn client() -> Result<reqwest::Client> {
+    reqwest::Client::builder()
+        .timeout(std::time::Duration::from_secs(20))
+        .build()
+        .context("build http client")
+}
+
+/// Resolve the master `J1` bearer: explicit `session_bearer` if non-empty, else
+/// the stored `master` session token.
+fn resolve_bearer(session_bearer: &str) -> Result<String> {
+    if !session_bearer.trim().is_empty() {
+        return Ok(session_bearer.trim().to_string());
+    }
+    let sess = agentkeys_core::session_store::load_session("master")
+        .context("no --session-bearer given and no stored `master` session to fall back on")?;
+    Ok(sess.token)
+}
+
+/// `agentkeys agent create` — master mints a one-time link code bound to the
+/// HDKD child omni for `label`, declaring the scope the agent should get.
+pub async fn agent_create(
+    broker_url: &str,
+    label: &str,
+    services: &str,
+    session_bearer: &str,
+) -> Result<String> {
+    let bearer = resolve_bearer(session_bearer)?;
+    let base = broker_url.trim_end_matches('/');
+    let resp = client()?
+        .post(format!("{base}/v1/agent/create"))
+        .bearer_auth(bearer)
+        .json(&json!({ "label": label, "requested_scope": services }))
+        .send()
+        .await
+        .context("POST /v1/agent/create")?;
+    let status = resp.status();
+    let text = resp.text().await.unwrap_or_default();
+    if !status.is_success() {
+        return Err(anyhow!("agent create failed: HTTP {status}: {text}"));
+    }
+    let v: Value = serde_json::from_str(&text).with_context(|| format!("parse: {text}"))?;
+    Ok(serde_json::to_string_pretty(&v)?)
+}
+
+/// `agentkeys agent pending` — master pulls redeemed-but-unbound agents (the
+/// production push-notification substrate). Each row is "agent-X wants to pair,
+/// wants `[requested_scope]`", with the device artifact (`device_pubkey`,
+/// `pop_sig`, `device_key_hash`) the master needs to submit `registerAgentDevice`.
+pub async fn agent_pending(broker_url: &str, session_bearer: &str) -> Result<String> {
+    let bearer = resolve_bearer(session_bearer)?;
+    let base = broker_url.trim_end_matches('/');
+    let resp = client()?
+        .get(format!("{base}/v1/agent/pending-bindings"))
+        .bearer_auth(bearer)
+        .send()
+        .await
+        .context("GET /v1/agent/pending-bindings")?;
+    let status = resp.status();
+    let text = resp.text().await.unwrap_or_default();
+    if !status.is_success() {
+        return Err(anyhow!("agent pending failed: HTTP {status}: {text}"));
+    }
+    let v: Value = serde_json::from_str(&text).with_context(|| format!("parse: {text}"))?;
+    Ok(serde_json::to_string_pretty(&v)?)
+}
diff --git a/crates/agentkeys-cli/src/lib.rs b/crates/agentkeys-cli/src/lib.rs
index e655650b..10b9c4fb 100644
--- a/crates/agentkeys-cli/src/lib.rs
+++ b/crates/agentkeys-cli/src/lib.rs
@@ -1,6 +1,7 @@
 use std::collections::HashMap;
 use std::sync::Arc;
 
+pub mod agent_admin;
 pub mod device_session;
 pub mod hook;
 pub mod k11;
diff --git a/crates/agentkeys-cli/src/main.rs b/crates/agentkeys-cli/src/main.rs
index 8ca1d4b3..5e6fa521 100644
--- a/crates/agentkeys-cli/src/main.rs
+++ b/crates/agentkeys-cli/src/main.rs
@@ -688,6 +688,50 @@ enum AgentAction {
         #[arg(long, help = "Force a fresh device key → fresh pairing (new omni)")]
         regen: bool,
     },
+    /// Master mints a one-time §10.2 link code bound to the HDKD child omni for
+    /// `--label`, declaring the scope the agent should get. Hand the code to the
+    /// agent; it redeems via `agentkeys-daemon --init-link-code`. (issue #144)
+    #[command(about = "Master: mint a one-time agent link code (HDKD child omni)")]
+    Create {
+        #[arg(long, help = "HDKD child label, e.g. agent-a (^[a-z0-9-]{1,32}$)")]
+        label: String,
+        #[arg(
+            long,
+            default_value = "memory",
+            help = "Scope the agent should get (the app-manifest); granted at approve"
+        )]
+        services: String,
+        #[arg(
+            long,
+            env = "AGENTKEYS_BROKER_URL",
+            help = "Broker base URL (OIDC issuer)"
+        )]
+        broker_url: String,
+        #[arg(
+            long,
+            default_value = "",
+            help = "Master J1 bearer (defaults to the stored `master` session)"
+        )]
+        session_bearer: String,
+    },
+    /// Master pulls redeemed-but-unbound agents — "agent-X wants to pair + wants
+    /// [scope]" — the production push-notification substrate. Each row carries
+    /// the device artifact the master submits with registerAgentDevice. (issue #144)
+    #[command(about = "Master: list agents awaiting binding approval")]
+    Pending {
+        #[arg(
+            long,
+            env = "AGENTKEYS_BROKER_URL",
+            help = "Broker base URL (OIDC issuer)"
+        )]
+        broker_url: String,
+        #[arg(
+            long,
+            default_value = "",
+            help = "Master J1 bearer (defaults to the stored `master` session)"
+        )]
+        session_bearer: String,
+    },
 }
 
 async fn cmd_chain(ctx: &CommandContext, action: &ChainAction) -> anyhow::Result<String> {
@@ -1127,6 +1171,24 @@ async fn main() {
                 )
                 .await
             }
+            AgentAction::Create {
+                label,
+                services,
+                broker_url,
+                session_bearer,
+            } => {
+                agentkeys_cli::agent_admin::agent_create(
+                    broker_url,
+                    label,
+                    services,
+                    session_bearer,
+                )
+                .await
+            }
+            AgentAction::Pending {
+                broker_url,
+                session_bearer,
+            } => agentkeys_cli::agent_admin::agent_pending(broker_url, session_bearer).await,
         },
     };
 
diff --git a/crates/agentkeys-core/Cargo.toml b/crates/agentkeys-core/Cargo.toml
index ffdc3392..986ee68e 100644
--- a/crates/agentkeys-core/Cargo.toml
+++ b/crates/agentkeys-core/Cargo.toml
@@ -33,6 +33,9 @@ rand = "0.8"
 # (tests, CLI preview); sha3 for keccak256 in the EIP-712 encoder.
 k256 = { version = "0.13", features = ["ecdsa", "sha2"] }
 sha3 = "0.10"
+# Issue #144 — device_crypto keygen (SigningKey::random). Same rand_core version
+# as the CLI/broker so the workspace lock is unchanged.
+rand_core = { version = "0.6", features = ["std"] }
 
 [dev-dependencies]
 tempfile = "3"
diff --git a/crates/agentkeys-core/src/actor_omni.rs b/crates/agentkeys-core/src/actor_omni.rs
index ed35f045..0908d61e 100644
--- a/crates/agentkeys-core/src/actor_omni.rs
+++ b/crates/agentkeys-core/src/actor_omni.rs
@@ -62,6 +62,71 @@ pub fn actor_omni_hex(wallet: &WalletAddress) -> String {
     hex::encode(actor_omni_from_wallet(wallet))
 }
 
+/// Domain tag for HDKD child-omni derivation (issue #144 / arch.md §6.2).
+/// Distinct from `DOMAIN` so a wallet-omni and a child-omni can never collide.
+const HDKD_DOMAIN: &[u8] = b"agentkeys-hdkd-v1";
+
+/// Validate an HDKD child label (`^[a-z0-9-]{1,32}$`). The label is spliced into
+/// the child-omni digest AND stored/echoed on chain + in JWT claims, so it must
+/// be a tight charset (no path separators, no whitespace, no uppercase).
+pub fn validate_label(label: &str) -> anyhow::Result<()> {
+    if label.is_empty() || label.len() > 32 {
+        return Err(anyhow::anyhow!(
+            "label must be 1..=32 chars, got {}",
+            label.len()
+        ));
+    }
+    if !label
+        .bytes()
+        .all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'-')
+    {
+        return Err(anyhow::anyhow!("label must match ^[a-z0-9-]+$: {label}"));
+    }
+    Ok(())
+}
+
+/// HDKD child actor omni (issue #144 / arch.md §6.2):
+///
+/// ```text
+/// O_child = SHA256(HDKD_DOMAIN || O_parent_bytes || "//" || label)
+/// ```
+///
+/// **PUBLIC + recomputable** (decision 2): anyone holding the parent omni + label
+/// can recompute the child — unforgeability comes from the master-gated
+/// `/v1/agent/create` (needs `J1_master`) + the master-submitted on-chain binding,
+/// NOT from a secret. The agent's K10 device key is decoupled from this omni.
+/// `master_omni` is the parent's 32 raw omni bytes (NOT the hex ASCII).
+pub fn child_omni(master_omni: &[u8; 32], label: &str) -> [u8; 32] {
+    let mut hasher = Sha256::new();
+    hasher.update(HDKD_DOMAIN);
+    hasher.update(master_omni);
+    hasher.update(b"//");
+    hasher.update(label.as_bytes());
+    let digest = hasher.finalize();
+    let mut out = [0u8; 32];
+    out.copy_from_slice(&digest);
+    out
+}
+
+/// [`child_omni`] over a hex parent omni (`0x`-prefixed or not), returning the
+/// child as **un-prefixed** 64-char lowercase hex — matching the `omni_account`
+/// JWT claim, the `agentkeys_actor_omni` PrincipalTag, and the `bots/<hex>/...`
+/// S3 prefix. Does NOT validate the label; call [`validate_label`] first.
+pub fn child_omni_hex(master_omni_hex: &str, label: &str) -> anyhow::Result<String> {
+    let h = master_omni_hex.trim();
+    let h = h.strip_prefix("0x").unwrap_or(h);
+    let bytes = hex::decode(h).map_err(|e| anyhow::anyhow!("parent omni not hex: {e}"))?;
+    if bytes.len() != 32 {
+        return Err(anyhow::anyhow!(
+            "parent omni must be 32 bytes, got {}",
+            bytes.len()
+        ));
+    }
+    let mut master = [0u8; 32];
+    master.copy_from_slice(&bytes);
+    Ok(hex::encode(child_omni(&master, label)))
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -109,4 +174,63 @@ mod tests {
         let expected = hex::encode(hasher.finalize());
         assert_eq!(hex, expected);
     }
+
+    #[test]
+    fn child_omni_pinned_known_value() {
+        // Frozen vector: a drive-by edit to HDKD_DOMAIN or the input layout
+        // trips this immediately. Recompute only on an intentional §6.2 change.
+        let master = [0u8; 32];
+        let got = child_omni(&master, "agent-a");
+        let mut hasher = Sha256::new();
+        hasher.update(b"agentkeys-hdkd-v1");
+        hasher.update(master);
+        hasher.update(b"//");
+        hasher.update(b"agent-a");
+        let expected: [u8; 32] = hasher.finalize().into();
+        assert_eq!(got, expected);
+    }
+
+    #[test]
+    fn child_omni_hex_is_un_prefixed_64_and_prefix_agnostic() {
+        let parent = "00".repeat(32);
+        let c = child_omni_hex(&parent, "agent-a").unwrap();
+        assert_eq!(c.len(), 64);
+        assert!(!c.starts_with("0x"));
+        assert!(c.chars().all(|ch| ch.is_ascii_hexdigit()));
+        // A 0x-prefixed parent yields the identical child.
+        assert_eq!(
+            c,
+            child_omni_hex(&format!("0x{parent}"), "agent-a").unwrap()
+        );
+    }
+
+    #[test]
+    fn child_omni_distinct_per_label_and_parent() {
+        let p1 = "11".repeat(32);
+        let p2 = "22".repeat(32);
+        assert_ne!(
+            child_omni_hex(&p1, "agent-a").unwrap(),
+            child_omni_hex(&p1, "agent-b").unwrap()
+        );
+        assert_ne!(
+            child_omni_hex(&p1, "agent-a").unwrap(),
+            child_omni_hex(&p2, "agent-a").unwrap()
+        );
+    }
+
+    #[test]
+    fn child_omni_hex_rejects_bad_parent_len() {
+        assert!(child_omni_hex("0xdeadbeef", "agent-a").is_err());
+    }
+
+    #[test]
+    fn validate_label_accepts_good_rejects_bad() {
+        assert!(validate_label("agent-a").is_ok());
+        assert!(validate_label("a1-b2-c3").is_ok());
+        assert!(validate_label("").is_err());
+        assert!(validate_label("Agent-A").is_err()); // uppercase
+        assert!(validate_label("agent/a").is_err()); // path sep
+        assert!(validate_label("agent a").is_err()); // whitespace
+        assert!(validate_label(&"a".repeat(33)).is_err()); // too long
+    }
 }
diff --git a/crates/agentkeys-core/src/device_crypto.rs b/crates/agentkeys-core/src/device_crypto.rs
new file mode 100644
index 00000000..81a2e0d0
--- /dev/null
+++ b/crates/agentkeys-core/src/device_crypto.rs
@@ -0,0 +1,277 @@
+//! Shared device-key crypto for the §10.2 agent bootstrap (issue #144).
+//!
+//! De-duplicates the secp256k1 / EIP-191 / keccak helpers previously inlined in
+//! `agentkeys-cli::device_session` and the broker's `plugins::auth::wallet_sig`,
+//! so the daemon (keygen + link-code redeem), the CLI (interim device-session),
+//! and the broker (redeem `pop_sig` verify) agree byte-for-byte.
+//!
+//! The proof-of-possession preimage is the **deployed** one —
+//! `keccak256("agentkeys-agent-pop:" || device_key_hash_hex)` — matching
+//! `scripts/heima-agent-create.sh` and the on-chain `registerAgentDevice` inputs.
+//! (arch.md §10.2 still shows the stale `link_code || D_pub`; the doc is being
+//! reconciled to this preimage, not the other way around.)
+
+use std::path::Path;
+
+use anyhow::{anyhow, Context, Result};
+use k256::ecdsa::{RecoveryId, Signature, SigningKey, VerifyingKey};
+use sha3::{Digest, Keccak256};
+
+/// Keccak-256 over `bytes`.
+pub fn keccak256(bytes: &[u8]) -> [u8; 32] {
+    let mut h = Keccak256::new();
+    h.update(bytes);
+    h.finalize().into()
+}
+
+/// EVM address (`0x` + 40 lowercase hex) = last 20 bytes of
+/// keccak256(uncompressed pubkey x‖y).
+pub fn evm_address(vk: &VerifyingKey) -> String {
+    let point = vk.to_encoded_point(false);
+    let xy = &point.as_bytes()[1..]; // drop the 0x04 SEC1 tag → 64 bytes
+    let hash = keccak256(xy);
+    format!("0x{}", hex::encode(&hash[12..]))
+}
+
+/// `device_key_hash = keccak256(address_bytes)` as `0x` + 64 hex. `addr` may be
+/// `0x`-prefixed and any case; the 20 raw address bytes are hashed (not ASCII).
+pub fn device_key_hash(addr: &str) -> Result<String> {
+    let addr_lc = addr.trim().to_lowercase();
+    let hex_part = addr_lc.strip_prefix("0x").unwrap_or(&addr_lc);
+    let addr_bytes = hex::decode(hex_part).context("address is not hex")?;
+    if addr_bytes.len() != 20 {
+        return Err(anyhow!(
+            "address must be 20 bytes, got {}",
+            addr_bytes.len()
+        ));
+    }
+    Ok(format!("0x{}", hex::encode(keccak256(&addr_bytes))))
+}
+
+/// The agent proof-of-possession preimage:
+/// `keccak256("agentkeys-agent-pop:" || device_key_hash_hex)`, where
+/// `device_key_hash_hex` is the `0x`-prefixed string from [`device_key_hash`].
+pub fn agent_pop_payload(device_key_hash_hex: &str) -> [u8; 32] {
+    keccak256(format!("agentkeys-agent-pop:{device_key_hash_hex}").as_bytes())
+}
+
+/// EIP-191 `personal_sign` over `message`, producing 65-byte `r‖s‖v` hex
+/// (`v ∈ {27,28}`, low-s via k256). Matches the broker's ecrecover envelope.
+pub fn eip191_sign(sk: &SigningKey, message: &[u8]) -> Result<String> {
+    let prefix = format!("\x19Ethereum Signed Message:\n{}", message.len());
+    let mut h = Keccak256::new();
+    h.update(prefix.as_bytes());
+    h.update(message);
+    let digest = h.finalize();
+    let (sig, recid): (Signature, RecoveryId) = sk
+        .sign_prehash_recoverable(&digest)
+        .context("sign_prehash_recoverable")?;
+    let mut out = sig.to_bytes().to_vec(); // 64 bytes r‖s
+    out.push(27 + recid.to_byte());
+    Ok(format!("0x{}", hex::encode(out)))
+}
+
+/// EIP-191 ecrecover: recover the `0x`-lowercase signer address from a 65-byte
+/// `r‖s‖v` hex signature over `message`. `v ∈ {0,1,27,28}`.
+pub fn ecrecover_eip191(message: &[u8], signature_hex: &str) -> Result<String> {
+    let sig_hex = signature_hex.trim().trim_start_matches("0x");
+    let sig_bytes = hex::decode(sig_hex).context("signature is not hex")?;
+    if sig_bytes.len() != 65 {
+        return Err(anyhow!(
+            "signature must be 65 bytes, got {}",
+            sig_bytes.len()
+        ));
+    }
+    let recovery_id_byte = match sig_bytes[64] {
+        v @ (0 | 1) => v,
+        v @ (27 | 28) => v - 27,
+        other => return Err(anyhow!("unsupported v byte: {other}")),
+    };
+    let recovery_id = RecoveryId::try_from(recovery_id_byte).context("bad recovery id")?;
+    let signature = Signature::from_slice(&sig_bytes[..64]).context("bad sig bytes")?;
+    let prefix = format!("\x19Ethereum Signed Message:\n{}", message.len());
+    let mut h = Keccak256::new();
+    h.update(prefix.as_bytes());
+    h.update(message);
+    let digest = h.finalize();
+    let vk = VerifyingKey::recover_from_prehash(&digest, &signature, recovery_id)
+        .map_err(|e| anyhow!("recover failed: {e}"))?;
+    Ok(evm_address(&vk))
+}
+
+fn expand_home(p: &str) -> String {
+    if let Some(rest) = p.strip_prefix("~/") {
+        if let Ok(home) = std::env::var("HOME") {
+            return format!("{home}/{rest}");
+        }
+    }
+    p.to_string()
+}
+
+#[cfg(unix)]
+pub fn write_key_0600(path: &str, content: &str) -> Result<()> {
+    use std::io::Write;
+    use std::os::unix::fs::OpenOptionsExt;
+    let mut f = std::fs::OpenOptions::new()
+        .write(true)
+        .create(true)
+        .truncate(true)
+        .mode(0o600)
+        .open(path)
+        .with_context(|| format!("open {path} (0600)"))?;
+    f.write_all(content.as_bytes())?;
+    Ok(())
+}
+
+#[cfg(not(unix))]
+pub fn write_key_0600(path: &str, content: &str) -> Result<()> {
+    std::fs::write(path, content).with_context(|| format!("write {path}"))
+}
+
+/// Before loading an EXISTING device key, verify it's a regular, owner-only
+/// file. A copied/restored key with group/other read bits — or a symlink to
+/// another file — would otherwise still produce a valid signer, silently
+/// breaking the "key never leaves / only the owner can use it" guarantee. We
+/// reject (not auto-repair): loose perms mean the key may already be exposed.
+#[cfg(unix)]
+pub fn enforce_owner_only(path: &str) -> Result<()> {
+    use std::os::unix::fs::PermissionsExt;
+    let meta = std::fs::symlink_metadata(path).with_context(|| format!("stat {path}"))?;
+    if meta.file_type().is_symlink() {
+        return Err(anyhow!(
+            "device key {path} is a symlink — refusing (key-custody); use a real owner-only file or regenerate"
+        ));
+    }
+    if !meta.file_type().is_file() {
+        return Err(anyhow!(
+            "device key {path} is not a regular file — refusing"
+        ));
+    }
+    let mode = meta.permissions().mode() & 0o777;
+    if mode & 0o077 != 0 {
+        return Err(anyhow!(
+            "device key {path} has loose permissions {mode:o} (group/other bits set) — \
+             it may already be exposed. Run `chmod 600 {path}` (or regenerate) and retry."
+        ));
+    }
+    Ok(())
+}
+
+#[cfg(not(unix))]
+pub fn enforce_owner_only(_path: &str) -> Result<()> {
+    Ok(())
+}
+
+/// An agent's secp256k1 device key (K10). Generated IN THE SANDBOX and never
+/// leaves it; used only for the redeem `pop_sig` and per-request cap-mint sigs.
+/// Its omni is decoupled from this key (issue #144 decision 2 — the omni is the
+/// broker-minted HDKD child).
+pub struct DeviceKey {
+    sk: SigningKey,
+    address: String,
+}
+
+impl DeviceKey {
+    /// Load the owner-only key file if present (rejecting loose perms / symlinks),
+    /// else generate a fresh key and persist it `0600`. `regen` forces a fresh
+    /// key. `key_file` may use a leading `~/`.
+    ///
+    /// On a failed bind/grant the caller should re-run WITHOUT `regen` so the
+    /// same key (→ same `device_key_hash`) is reused and the on-chain submit
+    /// hits the `already-registered` short-circuit instead of binding a 2nd key.
+    pub fn load_or_generate(key_file: &str, regen: bool) -> Result<Self> {
+        let key_path = expand_home(key_file);
+        if regen {
+            let _ = std::fs::remove_file(&key_path);
+        }
+        let sk = if Path::new(&key_path).exists() {
+            enforce_owner_only(&key_path)?;
+            let raw = std::fs::read_to_string(&key_path).context("read device key file")?;
+            let raw = raw.trim().trim_start_matches("0x");
+            let bytes = hex::decode(raw).context("device key file is not hex")?;
+            SigningKey::from_slice(&bytes).context("invalid secp256k1 device key")?
+        } else {
+            let sk = SigningKey::random(&mut rand_core::OsRng);
+            if let Some(dir) = Path::new(&key_path).parent() {
+                std::fs::create_dir_all(dir).ok();
+            }
+            write_key_0600(&key_path, &format!("0x{}", hex::encode(sk.to_bytes())))?;
+            sk
+        };
+        let address = evm_address(sk.verifying_key());
+        Ok(Self { sk, address })
+    }
+
+    /// The K10 EVM address (`0x` + 40 lowercase hex).
+    pub fn address(&self) -> &str {
+        &self.address
+    }
+
+    /// `device_key_hash = keccak256(address_bytes)`.
+    pub fn device_key_hash(&self) -> Result<String> {
+        device_key_hash(&self.address)
+    }
+
+    /// EIP-191 sign `message` with this device key.
+    pub fn sign_eip191(&self, message: &[u8]) -> Result<String> {
+        eip191_sign(&self.sk, message)
+    }
+
+    /// Proof-of-possession signature the broker verifies at link-code redeem and
+    /// the master submits with `registerAgentDevice`:
+    /// `EIP-191( keccak256("agentkeys-agent-pop:" || device_key_hash) )`.
+    pub fn pop_sig(&self) -> Result<String> {
+        let dkh = self.device_key_hash()?;
+        self.sign_eip191(&agent_pop_payload(&dkh))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn eip191_round_trip_recovers_signer() {
+        let sk = SigningKey::random(&mut rand_core::OsRng);
+        let addr = evm_address(sk.verifying_key());
+        let msg = b"hello agentkeys";
+        let sig = eip191_sign(&sk, msg).unwrap();
+        let recovered = ecrecover_eip191(msg, &sig).unwrap();
+        assert_eq!(recovered, addr);
+    }
+
+    #[test]
+    fn pop_sig_recovers_to_device_address() {
+        // The redeem-critical match: the broker recovers the device address from
+        // pop_sig over agent_pop_payload(device_key_hash) and checks it equals
+        // the supplied device_pubkey.
+        let dir = tempfile::tempdir().unwrap();
+        let kf = dir.path().join("dev.key");
+        let dk = DeviceKey::load_or_generate(kf.to_str().unwrap(), true).unwrap();
+        let dkh = dk.device_key_hash().unwrap();
+        let pop = dk.pop_sig().unwrap();
+        let recovered = ecrecover_eip191(&agent_pop_payload(&dkh), &pop).unwrap();
+        assert_eq!(recovered, dk.address());
+    }
+
+    #[test]
+    fn device_key_persists_and_reloads_same_address() {
+        let dir = tempfile::tempdir().unwrap();
+        let kf = dir.path().join("dev.key");
+        let a = DeviceKey::load_or_generate(kf.to_str().unwrap(), false).unwrap();
+        let b = DeviceKey::load_or_generate(kf.to_str().unwrap(), false).unwrap();
+        assert_eq!(a.address(), b.address());
+    }
+
+    #[test]
+    fn device_key_hash_is_0x_64_hex() {
+        let h = device_key_hash("0x0000000000000000000000000000000000000000").unwrap();
+        assert!(h.starts_with("0x"));
+        assert_eq!(h.len(), 66);
+    }
+
+    #[test]
+    fn ecrecover_rejects_wrong_length() {
+        assert!(ecrecover_eip191(b"x", "0x00").is_err());
+    }
+}
diff --git a/crates/agentkeys-core/src/lib.rs b/crates/agentkeys-core/src/lib.rs
index b9fedcaa..5b5926c4 100644
--- a/crates/agentkeys-core/src/lib.rs
+++ b/crates/agentkeys-core/src/lib.rs
@@ -4,6 +4,7 @@ pub mod auth_request;
 pub mod backend;
 pub mod chain_profile;
 pub mod clear_signing;
+pub mod device_crypto;
 pub mod init_flow;
 pub mod mock_client;
 pub mod otp;
diff --git a/crates/agentkeys-daemon/src/main.rs b/crates/agentkeys-daemon/src/main.rs
index e7187dd3..19f6bf0d 100644
--- a/crates/agentkeys-daemon/src/main.rs
+++ b/crates/agentkeys-daemon/src/main.rs
@@ -1,11 +1,11 @@
 use std::sync::Arc;
-use std::time::Duration;
+use std::time::{Duration, SystemTime, UNIX_EPOCH};
 
 use agentkeys_core::backend::CredentialBackend;
 use agentkeys_core::init_flow;
 use agentkeys_core::mock_client::MockHttpClient;
 use agentkeys_core::session_store;
-use agentkeys_types::WalletAddress;
+use agentkeys_types::{Session, WalletAddress};
 use anyhow::Context;
 use clap::Parser;
 use tracing::info;
@@ -169,6 +169,23 @@ struct Args {
     /// or OAuth2 callback before failing init.
     #[arg(long, default_value_t = 300)]
     init_poll_timeout_seconds: u64,
+
+    /// Issue #144 §10.2: redeem a one-time master-issued link code. Generates
+    /// (or reuses) the K10 device key IN THE SANDBOX, POSTs
+    /// `/v1/auth/link-code/redeem`, persists `J1_agent`, and prints the binding
+    /// artifact (device_pubkey + pop_sig + omnis) on stdout for the master to
+    /// submit `registerAgentDevice`. One-shot: redeems and exits (the MCP/proxy
+    /// surface runs as a separate process per §22c). Requires `--broker-url`.
+    #[arg(long, conflicts_with_all = ["init_email", "init_oauth2_google", "recover"])]
+    init_link_code: Option<String>,
+
+    /// Path to the agent's K10 device-key file for `--init-link-code`. Defaults
+    /// to the same path as `agentkeys agent device-session`
+    /// (`~/.agentkeys/agent-device.key`) so the CLI + daemon share one key.
+    /// Reused on retry (never auto-regenerated) so a re-run after a failed master
+    /// bind/grant keeps the same `device_key_hash` (already-registered skip).
+    #[arg(long, env = "AGENTKEYS_DEVICE_KEY_FILE")]
+    device_key_file: Option<String>,
 }
 
 #[tokio::main]
@@ -191,6 +208,13 @@ async fn main() -> anyhow::Result<()> {
         return run_proxy_mode(args).await;
     }
 
+    // Issue #144 §10.2 one-shot bootstrap: redeem a link code, persist J1_agent,
+    // emit the binding artifact, exit. Runs before the --backend requirement +
+    // hardening (it needs neither — only --broker-url + the OS RNG for keygen).
+    if let Some(code) = args.init_link_code.clone() {
+        return run_link_code_bootstrap(args, &code).await;
+    }
+
     // 1. Apply kernel hardening
     let _hardening_report = hardening::apply_hardening()?;
 
@@ -416,6 +440,121 @@ async fn main() -> anyhow::Result<()> {
     Ok(())
 }
 
+/// Issue #144 §10.2 one-shot agent bootstrap: generate (or reuse) the K10 device
+/// key in the sandbox, redeem the master-issued link code at the broker, persist
+/// `J1_agent`, and print the binding artifact the master needs to submit
+/// `registerAgentDevice`. The device key NEVER leaves this machine.
+///
+/// Logs go to stderr; the JSON artifact is the ONLY thing on stdout, so the wire
+/// harness can capture it and hand it to the master's bind step (same shape
+/// `scripts/heima-agent-create.sh --from-pubkey` consumes).
+async fn run_link_code_bootstrap(args: Args, link_code: &str) -> anyhow::Result<()> {
+    use agentkeys_core::device_crypto::DeviceKey;
+
+    let broker_url = args.broker_url.clone().ok_or_else(|| {
+        anyhow::anyhow!("--broker-url (or AGENTKEYS_BROKER_URL) required for --init-link-code")
+    })?;
+    let base = broker_url.trim_end_matches('/').to_string();
+
+    let key_file = args
+        .device_key_file
+        .clone()
+        .unwrap_or_else(|| "~/.agentkeys/agent-device.key".to_string());
+    // Reuse the existing key on retry (no regen): a failed master bind/grant
+    // must re-redeem with the SAME device_key_hash so the on-chain submit hits
+    // the already-registered short-circuit instead of binding a second key.
+    let dk =
+        DeviceKey::load_or_generate(&key_file, false).context("load/generate K10 device key")?;
+    let device_pubkey = dk.address().to_string();
+    let device_key_hash = dk.device_key_hash().context("device_key_hash")?;
+    let pop_sig = dk.pop_sig().context("pop_sig")?;
+
+    let client = reqwest::Client::builder()
+        .timeout(Duration::from_secs(20))
+        .build()
+        .context("build http client")?;
+    let resp = client
+        .post(format!("{base}/v1/auth/link-code/redeem"))
+        .json(&serde_json::json!({
+            "link_code": link_code,
+            "device_pubkey": device_pubkey,
+            "pop_sig": pop_sig,
+        }))
+        .send()
+        .await
+        .context("POST /v1/auth/link-code/redeem")?;
+    let status = resp.status();
+    let text = resp.text().await.unwrap_or_default();
+    if !status.is_success() {
+        anyhow::bail!("link-code redeem failed: HTTP {status}: {text}");
+    }
+    let body: serde_json::Value =
+        serde_json::from_str(&text).with_context(|| format!("parse redeem response: {text}"))?;
+    let session_jwt = body
+        .get("session_jwt")
+        .and_then(|v| v.as_str())
+        .ok_or_else(|| anyhow::anyhow!("redeem response missing session_jwt: {text}"))?;
+    let child_omni = body
+        .get("child_omni")
+        .and_then(|v| v.as_str())
+        .unwrap_or_default();
+    let operator_omni = body
+        .get("operator_omni")
+        .and_then(|v| v.as_str())
+        .unwrap_or_default();
+    let derivation_path = body
+        .get("derivation_path")
+        .and_then(|v| v.as_str())
+        .unwrap_or_default();
+
+    // Persist J1_agent so a daemon restart resumes (Session.wallet = K10 address;
+    // the HDKD omni rides inside the J1 claims, not in Session.wallet).
+    let now = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map(|d| d.as_secs())
+        .unwrap_or(0);
+    let sess = Session {
+        token: session_jwt.to_string(),
+        wallet: WalletAddress(device_pubkey.clone()),
+        scope: None,
+        created_at: now,
+        ttl_seconds: 18_000,
+    };
+    let sid = args
+        .session_id
+        .clone()
+        .unwrap_or_else(|| format!("daemon-{child_omni}"));
+    session_store::save_session(&sess, &sid).context("save link-code session")?;
+
+    info!(
+        target: "agentkeys.daemon.init",
+        child_omni = %child_omni,
+        operator_omni = %operator_omni,
+        device = %device_pubkey,
+        session_id = %sid,
+        "agentkeys-daemon redeemed §10.2 link code — J1_agent persisted"
+    );
+
+    // Binding artifact on STDOUT (logs are on stderr). Same fields the master's
+    // chain helper consumes; pop_sig + device_key_hash let the master submit
+    // registerAgentDevice without re-deriving.
+    println!(
+        "{}",
+        serde_json::json!({
+            "agent_address": device_pubkey,
+            "actor_omni": child_omni,
+            "operator_omni": operator_omni,
+            "derivation_path": derivation_path,
+            "device_key_hash": device_key_hash,
+            "pop_sig": pop_sig,
+            "session_jwt": session_jwt,
+            "link_code": link_code,
+            "key_file": key_file,
+        })
+    );
+    Ok(())
+}
+
 /// Drive the issue-#74-step-1 bootstrap chain. Reads `--init-email` /
 /// `--init-oauth2-google` / `--signer-url` / `--broker-url` /
 /// `--init-chain-id` / `--init-poll-timeout-seconds` from `args` and
diff --git a/docs/arch.md b/docs/arch.md
index d1f69cdc..fff94b09 100644
--- a/docs/arch.md
+++ b/docs/arch.md
@@ -204,7 +204,7 @@ Pinned to disambiguate the same value showing up under different labels across c
 | `actor_omni` | **The durable per-actor cryptographic anchor.** `SHA256("agentkeys" \|\| "evm" \|\| initial_master_wallet_K3_v1)`. **Frozen at first SIWE-bind**; never rotates with K3, never changes with wallet rotation. The Layer 1 identifier per §6. | `omni_account` (JWT claim + CLI `whoami` field), `agentkeys_actor_omni` (AWS PrincipalTag key), `OMNI_A` / `OMNI_B` (demo shell vars). |
 | `current_master_wallet` | **The current chain identity** = `HKDF(K3_v[current_epoch], O_master)`. Rotates each K3 epoch. Appears on chain as `msg.sender` in sovereign mode. The Layer 2 identifier per §6. | `master_wallet`, `wallet_address` (JWT claim shape pre-rotation), `MASTER_WALLET` (demo shell var). When historical K3 epochs are in scope, qualify with `master_wallet_K3_v[N]`. |
 | `identity_omni` | **The transient identity omni** — `SHA256("agentkeys" \|\| identity_type \|\| identity_value)`. Used internally by the broker between init and SIWE-verify; never carried in a post-SIWE JWT. | `identity_omni_email` / `identity_omni_oauth2` (when narrowing to a specific identity type), `identity omni` (init-flow CLI log line). |
-| `agent_omni` | **A child actor omni** = `HDKD(O_master, "//<label>")`. Hard derivation; child cannot be computed without parent's master secret. Distinct from `master_omni`; both are valid actor_omnis. | `O_master//agent-A`, `O_agent_A` (HDKD-tree notation). |
+| `agent_omni` | **A child actor omni** = `SHA256("agentkeys-hdkd-v1" \|\| O_master \|\| "//<label>")` (issue #144). **Public + recomputable** — anyone with the parent omni + label recomputes it; unforgeability is the master-gated `/v1/agent/create` + the master-submitted on-chain binding, NOT a secret. (The "cannot be computed without the parent's master secret" property lives one layer down, at the K4 wallet `HKDF(K3_v[epoch], agent_omni)` in the signer.) Distinct from `master_omni`; both are valid actor_omnis. | `O_master//agent-A`, `O_agent_A` (HDKD-tree notation). |
 | `K3` | The 32 bytes inside the signer enclave that K4 + KEK derivation HKDFs against. Per-epoch via `K3EpochCounter`. | `K3_v[N]` to disambiguate epoch; `master_secret` (signer-internal log term — discouraged). |
 | `session JWT` (= K6) | The bearer token at `~/.agentkeys/<id>/session.json` (or OS keychain). Signed by K1. Carries `agentkeys.actor_omni`, `agentkeys.device_pubkey`, `agentkeys.webauthn_cred_id` (master only). | `session_jwt`, `J1` (post-SIWE bearer), `SESSION_JWT_A` / `SESSION_JWT_B` (demo shell vars). |
 | `OIDC JWT` (= K7) | Per-mint short-lived JWT signed by K2; consumed by `AssumeRoleWithWebIdentity`. Carries `agentkeys_actor_omni` claim → AWS session tag. | `oidc_jwt`, `JWT_A` / `JWT_B` (demo shell vars). |
@@ -285,7 +285,7 @@ O_master                                wallet_master = HKDF(K3_v[epoch], O_mast
 └── ...
 ```
 
-Hard derivation (`//N`) — child secret cannot be computed without the parent's master secret. Substrate / SLIP-0010 standard. Each node's wallet is a different EVM address; AWS PrincipalTag is per-actor `actor_omni` for prefix isolation.
+The omni-tree edge `//<label>` is **public + recomputable** (issue #144): `O_child = SHA256("agentkeys-hdkd-v1" || O_parent || "//" || label)`. What "cannot be computed without the parent's master secret" is the per-node **wallet** (K4 = `HKDF(K3_v[epoch], O_node)`, derived in the signer) — not the omni node itself. Each node's wallet is a different EVM address; AWS PrincipalTag is per-actor `actor_omni` for prefix isolation. Only the master can *create* a binding for a child omni (the master-gated `/v1/agent/create` + the master-submitted `registerAgentDevice`), so a public omni derivation never lets anyone bind a sibling.
 
 **Why per-agent omni (not shared with master):**
 
@@ -473,42 +473,57 @@ Per §9 stages 0–4. Identity ceremonies vary per identity type but converge on
 
 ```
 ON MASTER (already initialized; holds J1_master):
-1. CLI: agentkeys agent create --label agent-A
+1. CLI: agentkeys agent create --label agent-A --services memory
 2. CLI → broker: POST /v1/agent/create
-                  { parent_omni: O_master, label: "agent-A", k11_assertion }
+                  { label: "agent-A", requested_scope: "memory" }
                   Authorization: Bearer J1_master
-3. Broker:
-   - Verify J1_master + K11 assertion (master-mutation gate)
-   - Derive O_agent_A = HDKD(O_master, "//agent-A")  [hard derivation]
-   - Persist (parent: O_master, child: O_agent_A, deriv_cert)
-   - Mint one-time link code bound to O_agent_A (TTL 600s)
-4. CLI: print link code (or auto-pipe to agent provisioner)
+3. Broker (J1_master bearer is the gate; K11 is NOT presented here — agents are
+   K10-only per the contract, so there is nothing for the broker to K11-verify):
+   - Verify J1_master
+   - Derive O_agent_A = SHA256(HDKD_DOMAIN || O_master || "//agent-A")
+     [public + recomputable per §6.2 — unforgeability is the J1_master gate +
+      the master-submitted on-chain binding, NOT a secret]
+   - Mint one-time link code bound to O_agent_A + requested_scope (TTL 600s)
+4. CLI: print link code (hand it to the agent out-of-band)
 
 ON AGENT MACHINE (any VM / container / CI runner / cloud sandbox):
-5. Stage 0: daemon generates (D_priv_agent, D_pub_agent) at startup
-            persists D_priv per §10.5
-6. agentkeys-daemon --init-link-code <code> --broker-url B --signer-url S
+5. Stage 0: daemon generates (D_priv_agent, D_pub_agent) IN THE SANDBOX
+            persists D_priv per §10.5 (reused on retry — never auto-regenerated)
+6. agentkeys-daemon --init-link-code <code> --broker-url B
 7. Daemon → broker: POST /v1/auth/link-code/redeem
-                     { link_code, device_pubkey: D_pub_agent,
-                       pop_sig: sign(D_priv_agent, link_code || D_pub_agent) }
+     { link_code, device_pubkey: D_pub_agent,
+       pop_sig: EIP-191( keccak256("agentkeys-agent-pop:" || device_key_hash) ) }
+     [device_key_hash = keccak256(D_pub_agent address bytes); this is the DEPLOYED
+      preimage — proves device-key possession, the link code proves authorization]
 8. Broker:
-   - Verify pop_sig
-   - Mark link code consumed (single-use)
-   - Bind (O_agent_A, D_pub_agent) on chain via
-     SidecarRegistry.register_agent_device(D_pub_hash, O_master, O_agent_A,
-                                            link_code_redemption, agent_pop_sig)
-     [tier=2, roles=CAP_MINT only, k11_cred_id=0]
-   - Mint J1_agent with claims:
-       actor_omni      = O_agent_A
-       parent_omni     = O_master
-       derivation_path = "//agent-A"
-       device_pubkey   = D_pub_agent
-9. Daemon: persist J1_agent; start the sidecar proxy (§12) and hand off any LLM-host integration to the MCP server surface per §22c.1 (backend variant decided at startup based on whether the LLM is local or remote)
+   - Verify pop_sig BEFORE consuming the code (a bad sig leaves the single-use
+     code redeemable → retryable)
+   - Mark link code consumed (single-use); record (D_pub_agent, pop_sig) as a
+     PENDING BINDING for the master
+   - Mint J1_agent { actor_omni=O_agent_A, parent_omni=O_master,
+                     derivation_path="//agent-A", device_pubkey=D_pub_agent }
+   - Does NOT write chain — the broker is read-only; the master binds (below)
+9. Daemon: persist J1_agent; emit the binding artifact. The agent now
+   authenticates but has NO scope yet (installed-but-not-yet-permitted).
+
+MASTER APPROVAL (async; master ≠ agent machine — the iOS/Android "first launch
+→ grant permissions" moment):
+10. Broker notifies the master (push notification in production). The master
+    pulls the pending binding (GET /v1/agent/pending-bindings, J1_master-gated) →
+    learns D_pub_agent + pop_sig it never generated.
+11. The master, with ONE K11/Touch ID approval, submits BOTH on chain:
+    - SidecarRegistry.registerAgentDevice(D_pub_hash, O_master, O_agent_A,
+        link_code_redemption, agent_pop_sig)   [msg.sender == operatorMasterWallet;
+        tier=AGENT, roles=CAP_MINT, k11_cred_id=0 — no biometric on this tx]
+    - AgentKeysScope.setScopeWithWebauthn(... requested_scope ...)  [the K11 gesture]
+    The CLI exposes these as two deterministic steps (test automation); the
+    operator experiences one approval. Install + permissions = one gesture.
+12. Agent's J1_agent now has scope; cap-mint works (§12).
 ```
 
-**Trust chain:** `master human → master K11 → master J1 + K10 sig → link-code-derivation-cert → agent K10 binding`. The agent never holds K11 or any user-presence credential.
+**Trust chain:** `master human → master K11 (at the approval) → master J1 + master-submitted on-chain binding → agent K10 binding`. The agent never holds K11 or any user-presence credential; the K11 gesture is the master's, exercised at step 11 (binding + scope), not at the broker.
 
-The agent's `pop_sig` is sufficient on its own (no WebAuthn equivalent) because the link code is single-use, TTL-bounded, and bound to a specific agent omni at mint time. Per-actor binding (§14) ensures the agent's K10 cannot mint caps under a sibling agent's omni.
+The agent's `pop_sig` proves K10 possession; the **link code** is the single-use, TTL-bounded, omni-bound authorization. Per-actor binding (§14) ensures the agent's K10 cannot mint caps under a sibling agent's omni. **The broker never writes chain** (decision: issue #144) — it mints the link code + `J1_agent` and records the pending binding; the master submits `registerAgentDevice` + the scope grant. (A faithful "broker binds at redeem" variant would need a contract change + a broker chain key — deferred.)
 
 ### 10.3 Master device switch + device-key rotation
 
@@ -764,8 +779,9 @@ The broker is the cap-mint authority. It does NOT hold credentials, K3, or any c
 /v1/auth/oauth2/{start,callback,status}       — OAuth2 flow (stage 1)
 /v1/auth/wallet/{start,verify}                — SIWE round-trip (stage 3)
 /v1/auth/bind/<request_id>                    — WebAuthn enrollment (stage 2)
-/v1/auth/link-code/redeem                     — agent bootstrap (§10.2)
-/v1/agent/create                              — mint agent link-code (master mutation, K11 required)
+/v1/auth/link-code/redeem                     — agent redeems link code → J1_agent (§10.2; no bearer, pop_sig-gated)
+/v1/agent/create                              — mint agent link-code (J1_master-gated; K11 NOT at broker — §10.2)
+/v1/agent/pending-bindings                    — master pulls redeemed-but-unbound agents to approve (§10.2)
 /v1/wallet/link                               — link wallet to identity (post-derive, pre-SIWE)
 /v1/wallet/device/rotate                      — K10 rotation (§10.3.2; K11 required)
 /v1/cap/cred-fetch                            — cap-mint for credential fetch
diff --git a/docs/operator-runbook-wire.md b/docs/operator-runbook-wire.md
index 50841ae1..98207e33 100644
--- a/docs/operator-runbook-wire.md
+++ b/docs/operator-runbook-wire.md
@@ -58,10 +58,11 @@ story. Each run does a **fresh pairing** (a brand-new agent identity), so expect
 3. **What happens, in order:**
    - **Phase 0** — prereqs + operator session (auto-minted from the master key).
    - **Phase 1** — sandbox up → Hermes installed → clean slate (1.2b) → binaries (re)built + uploaded (first build ~1 min).
-   - **Phase P — install (pair)** 📲
-     - `P.1` the agent generates its **own device key in the sandbox** + mints a session (the key never touches the master).
-     - `P.2` the master binds that device **on-chain** (`registerAgentDevice`).
-     - `P.3` **🔐 Touch ID** — the master *approves* the agent's `[memory]` permission (on-chain scope grant).
+   - **Phase P — install (pair)** 📲 (full §10.2 HDKD bootstrap, issue #144)
+     - `P.0` the **master** mints a one-time link code bound to the HDKD child omni `O_agent = SHA256(.. ‖ O_master ‖ "//label")` (real broker `/v1/agent/create`; no more `openssl` stub).
+     - `P.1` the **agent daemon** (`agentkeys-daemon --init-link-code`) generates its **own K10 device key in the sandbox**, proves possession, and **redeems** the code → `J1_agent` (the key never touches the master).
+     - `P.2` the master **binds** that device **on-chain** (`registerAgentDevice`, no biometric).
+     - `P.3` **🔐 Touch ID** — the master **grants** the agent's `[memory]` permission (`setScopeWithWebauthn`). Conceptually `P.2`+`P.3` are **one approval** (install + permissions, iOS/Android-style); kept as two steps for deterministic test automation.
    - **1.4–1.5** — MCP server (per-actor STS relay) starts; the fresh actor's memory is seeded (new identity ⇒ empty ⇒ seeds "Chengdu trip").
    - **Phase 2** — `agentkeys wire hermes` installs the IAM-gate hooks.
    - **Phase 4 — the surprise** — talk to Hermes and ask **"where am I going this weekend?"** → it recalls Chengdu (memory it *just earned permission to read*).
@@ -113,7 +114,7 @@ Note it puts the agent key back on the master; use only for quick loops.
 **Real mode only:**
 - The `setup-heima.sh` account already created (master device registered + contracts deployed; the harness verifies, never rebuilds). `OPERATOR_OMNI` is derived from your master key (`OPERATOR_KEY_FILE`); the **agent** identity is generated fresh in the sandbox by Phase P (no pre-existing agent file needed in the default fresh-pairing mode).
 - An **operator session JWT** for cap-mint. The harness now mints this **automatically and non-interactively**: step `0.7` decodes the on-disk session, and if it's missing, expired, **or for the wrong operator** (its `agentkeys.omni_account` ≠ the agent's `operator_omni`), it SIWE-signs a fresh one with `OPERATOR_KEY_FILE` (default `~/.agentkeys/heima-deployer.key` — the master key whose broker omni == `operator_omni`) via the broker's `wallet_sig` plugin. Requires `cast` (Foundry) on PATH. **Note:** the old `alice` email session is a *different* omni and is no longer used for cap-mint — set `OPERATOR_KEY_FILE` to the master key for your operator if the default isn't it. (Pass `AGENTKEYS_SESSION_BEARER` to override entirely.)
-- **For real memory (S3) to work:** **Phase P** generates the agent's device key **in the sandbox** and mints its **agent session** there (`agentkeys agent device-session`); the MCP server uses that session for the per-actor STS relay (`mint-oidc-jwt` → `AssumeRoleWithWebIdentity` → `X-Aws-*` headers to the worker), so the agent key never touches the master. Needs the per-data-class role ARNs (`MEMORY_ROLE_ARN`/`VAULT_ROLE_ARN`, from `operator-workstation.env`). Without the relay the worker falls back to its instance profile (no S3) and memory ops 502. (`--reuse-agent` instead mints the session on the master from `agent_private_key` in the agent file — legacy.)
+- **For real memory (S3) to work:** **Phase P** generates the agent's device key **in the sandbox** and redeems the master link code there (`agentkeys-daemon --init-link-code` → `J1_agent`); the MCP server uses that session for the per-actor STS relay (`mint-oidc-jwt` → `AssumeRoleWithWebIdentity` → `X-Aws-*` headers to the worker), so the agent key never touches the master. Needs the per-data-class role ARNs (`MEMORY_ROLE_ARN`/`VAULT_ROLE_ARN`, from `operator-workstation.env`). Without the relay the worker falls back to its instance profile (no S3) and memory ops 502. (`--reuse-agent` instead mints the session on the master from `agent_private_key` in the agent file — legacy.)
 - `export OPENROUTER_API_KEY=...` in `~/.zshenv` — the harness uses it as the LLM-key fallback (no prompt).
 - **For the Phase P scope grant (P.3):** the master's primary K11 enrolled in **webauthn** mode — `agentkeys k11 enroll --webauthn --rp-id localhost --operator-omni 0x<operator>`. Without it, `heima-scope-set.sh --webauthn` can't run and the freshly-paired agent never gets the memory scope (memory ops will be scope-rejected). Override the granted service list with `SEED_SCOPE_SERVICES` (it **sets** the full list, so include every service the agent needs).
 
@@ -212,8 +213,8 @@ Re-running `agentkeys wire hermes` is always safe — unchanged scripts/config s
 |---|---|---|
 | cap-mint → 401 `ExpiredSignature` | the operator session JWT expired | the harness now auto-mints a fresh one at `0.7` via `wallet_sig` (`OPERATOR_KEY_FILE`). If it didn't: ensure `cast` is on PATH and `OPERATOR_KEY_FILE` exists |
 | cap-mint → 401/`OperatorMismatch` (`session_omni != operator_omni`) | the session is for a *different* operator (e.g. the legacy `alice` email session, omni `4231cd8f…` ≠ agent operator `941cb1c3…`) | `0.7` now detects the omni mismatch and re-mints from `OPERATOR_KEY_FILE`. If `0.7` fails with "wrong operator", point `OPERATOR_KEY_FILE` at the master key whose broker omni == `operator_omni` |
-| memory put/get → HTTP **502** `{"reason":"s3_put"}` / `{"reason":"s3_get"}` | the MCP `http` backend didn't forward per-actor STS creds, so the worker fell back to its EC2 instance profile (SES-only, **no S3**) → AccessDenied on every op. cap-mint + chain-verify themselves SUCCEED (the agent IS authorized); the gap was the credential **relay**. | **Fixed (issue #90):** the backend now mints agent-tagged STS creds (`0.8` agent session → broker `/v1/mint-oidc-jwt` → `AssumeRoleWithWebIdentity(memory-role)`, tagged `agentkeys_actor_omni`) and forwards them as `X-Aws-*` headers, so AWS scopes S3 to `bots/<actor>/memory/`. If it still 502s: confirm `P.1 device-session` shows "agent paired" (or `0.8 agent session` under `--reuse-agent`) and `P.3 approve permissions` granted the scope; the relay needs the in-sandbox agent session + `MEMORY_ROLE_ARN`/`VAULT_ROLE_ARN`/`REGION` from `operator-workstation.env`. Optional strict enforcement: set `AGENTKEYS_WORKER_REQUIRE_STS=1` in the worker env (rejects credless requests with 401 instead of falling back). |
-| **Phase P** `P.1`/`P.2`/`P.3` fails | `P.1` device-session: stale sandbox `agentkeys` (no `agent device-session` subcommand) or broker `/v1/auth/wallet/*` down. `P.2` register: on-chain `registerAgentDevice` failed (master gas / RPC). `P.3` approve: `heima-scope-set --webauthn` needs K11 webauthn enrollment + Touch ID. | `P.1` 1.3 rebuilds+uploads the binary — just re-run. `P.2` check the master wallet balance / RPC. `P.3` enroll K11 webauthn + pass `--webauthn`. For a quick loop without pairing use `--reuse-agent`. |
+| memory put/get → HTTP **502** `{"reason":"s3_put"}` / `{"reason":"s3_get"}` | the MCP `http` backend didn't forward per-actor STS creds, so the worker fell back to its EC2 instance profile (SES-only, **no S3**) → AccessDenied on every op. cap-mint + chain-verify themselves SUCCEED (the agent IS authorized); the gap was the credential **relay**. | **Fixed (issue #90):** the backend now mints agent-tagged STS creds (`0.8` agent session → broker `/v1/mint-oidc-jwt` → `AssumeRoleWithWebIdentity(memory-role)`, tagged `agentkeys_actor_omni`) and forwards them as `X-Aws-*` headers, so AWS scopes S3 to `bots/<actor>/memory/`. If it still 502s: confirm `P.1 install` shows "agent redeemed in-sandbox" (or `0.8 agent session` under `--reuse-agent`) and `P.3 grant` granted the scope; the relay needs the in-sandbox agent session + `MEMORY_ROLE_ARN`/`VAULT_ROLE_ARN`/`REGION` from `operator-workstation.env`. Optional strict enforcement: set `AGENTKEYS_WORKER_REQUIRE_STS=1` in the worker env (rejects credless requests with 401 instead of falling back). |
+| **Phase P** `P.0`/`P.1`/`P.2`/`P.3` fails | `P.0` create: broker `/v1/agent/create` down or the operator session (0.7) invalid. `P.1` install: stale sandbox `agentkeys-daemon` (no `--init-link-code`), broker `/v1/auth/link-code/redeem` down, or an expired link code (>600s). `P.2` bind: on-chain `registerAgentDevice` failed (master gas / RPC). `P.3` grant: `heima-scope-set --webauthn` needs K11 webauthn enrollment + Touch ID. | `P.0` check 0.7 + the broker. `P.1` 1.3 rebuilds+uploads the daemon binary — just re-run (the agent reuses its K10, so a retry is safe). `P.2` check the master wallet balance / RPC. `P.3` enroll K11 webauthn + pass `--webauthn`. For a quick loop without pairing use `--reuse-agent`. |
 | `1.3 linux build` is slow even for a one-line change | rustup re-downloaded the host-pinned toolchain (~250 MB, ~4 min) because `/usr/local/rustup` wasn't cached | fixed: the toolchain now persists in the `RUSTUP_VOL` docker volume — the **first** build seeds it (~4 min), later builds skip the download (incremental compile only, ~15 s) |
 | Phase 1 `1.3 linux build` → "cannot pull" | Docker Hub unreachable for the base image | `RUST_BUILD_IMAGE=<local/mirror rust image>` or pre-pull `rust:1.83-slim-bookworm` |
 | `1.3 linux build` won't pick up a Rust edit | gate compares source mtime vs binary; re-runs rebuild automatically on a real edit | to force a from-scratch rebuild: `rm -rf target/sandbox-linux && docker volume rm agentkeys-sandbox-cargo-registry agentkeys-sandbox-cargo-git`; to rebuild the deps image: `docker rmi agentkeys-sandbox-builder:1.83-bookworm` |
diff --git a/docs/spec/plans/issue-144-hdkd-agent-bootstrap.md b/docs/spec/plans/issue-144-hdkd-agent-bootstrap.md
new file mode 100644
index 00000000..ee878313
--- /dev/null
+++ b/docs/spec/plans/issue-144-hdkd-agent-bootstrap.md
@@ -0,0 +1,55 @@
+# Issue #144 — Full arch.md §10.2 agent-bootstrap (HDKD omni + broker link-code endpoints)
+
+Converges the PR #141 **interim** §10.2 (agent omni derived from the agent's own
+wallet; `openssl rand` link-code stub) to the literal ceremony: the **master**
+mints a one-time link code bound to a **hard-derived child omni**
+`O_agent = SHA256("agentkeys-hdkd-v1" || O_master || "//label")`; the **agent
+daemon** generates its own K10 in the sandbox, redeems the code (proving K10
+possession via `pop_sig`), and the broker mints **`J1_agent`** carrying the HDKD
+omni + parent lineage. The master then approves the binding + scope async (push →
+one Touch ID), iOS/Android-style.
+
+## Decisions (asked + answered — see PR description)
+1. **Master submits the on-chain binding** (no contract change, no broker chain key). Broker mints the code + `J1_agent`, records a pending binding; the master pulls it and submits `registerAgentDevice` + `setScopeWithWebauthn`.
+2. **Child omni is PUBLIC + recomputable** (`SHA256(domain‖O_master‖//label)`); unforgeability = the J1_master-gated `/v1/agent/create` + master-submitted binding. Agent keeps a K10 device key only (omni decoupled from it).
+3. **Daemon owns keygen + redeem** (`--init-link-code`), sharing `agentkeys-core::device_crypto` with the CLI.
+
+## Implementation order (every step landed unless noted)
+
+| # | Step | Files | Status |
+|---|------|-------|--------|
+| 1 | Shared `device_crypto` (keccak/evm_address/eip191/ecrecover/pop + `DeviceKey`) | `crates/agentkeys-core/src/device_crypto.rs`, `lib.rs`, `Cargo.toml` (+`rand_core`) | ✅ |
+| 2 | HDKD `child_omni`/`child_omni_hex` + `validate_label` (+ frozen vectors) | `crates/agentkeys-core/src/actor_omni.rs` | ✅ |
+| 3 | Link-code + pending-binding store (SQLite, single-use, TTL 600s) | `crates/agentkeys-broker-server/src/storage/link_codes.rs` (+ `mod.rs`, `state.rs`, `boot.rs`, `main.rs`) | ✅ |
+| 4 | `AgentKeysClaims` + `mint_agent_session_jwt` (parent_omni/derivation_path/device_pubkey) | `jwt/verify.rs`, `jwt/issue.rs` | ✅ |
+| 5 | `POST /v1/agent/create` (J1_master-gated) | `handlers/agent/create.rs` | ✅ |
+| 6 | `POST /v1/auth/link-code/redeem` (pop_sig-gated, pre-consume verify) | `handlers/agent/redeem.rs` | ✅ |
+| 7 | `GET /v1/agent/pending-bindings` (J1_master-gated; push substrate) | `handlers/agent/pending.rs` | ✅ |
+| 8 | `mint-oidc-jwt` reads `actor_omni` from the claim (STS-relay prereq; wallet-session byte-identical) | `handlers/oidc.rs` | ✅ |
+| 9 | Route registration | `lib.rs`, `handlers/mod.rs`, `handlers/grant/mod.rs` (`require_session_jwt` → `pub(crate)`) | ✅ |
+| 10 | Daemon `--init-link-code` one-shot (keygen in sandbox → redeem → persist J1_agent → emit artifact) | `crates/agentkeys-daemon/src/main.rs` | ✅ |
+| 11 | CLI `agent create` + `agent pending` (master-side) | `crates/agentkeys-cli/src/agent_admin.rs`, `main.rs`, `lib.rs` | ✅ |
+| 12 | Harness Phase P: P.0 create (real code) → P.1 install (daemon) → P.2 bind → P.3 grant; build+upload daemon binary | `harness/phase1-wire-demo.sh` | ✅ |
+| 13 | Docs reconciliation (§10.2 steps, §5 `agent_omni`, §6.2, route list) | `docs/arch.md` | ✅ |
+| 14 | Runbook Phase P (daemon keygen + real code + retry note) | `docs/operator-runbook-wire.md` | ✅ |
+
+### Deviation note (vs the asked plan)
+The asked plan listed CLI `agent bind` + `agent grant` Rust subcommands. Chain
+submission lives in shell + `cast` by architecture, and the two existing chain
+helpers (`heima-agent-create.sh --from-pubkey` = **bind**, `heima-scope-set.sh
+--webauthn` = **grant**) already provide the deterministic two-step split the
+test drives. So the CLI ships `agent create` + `agent pending` (master-side, the
+genuinely-new broker surfaces incl. the production rendezvous); bind/grant remain
+the two shell helpers. The optional one-gesture `agent approve` wrapper is NOT
+implemented (the two helpers are the split). Documented for transparency.
+
+## Tests
+- `cargo test -p agentkeys-core` — `child_omni` frozen vector; `pop_sig` sign→ecrecover round-trip (redeem-critical).
+- `cargo test -p agentkeys-broker-server --features auth-email-link` — link-code store (issue/consume/TTL/single-use/pending/mark_bound/purge); `agent_bootstrap_flow` integration (create-gated, bad-label, full create→redeem→pending, bad-pop_sig-retryable); `mint-oidc-jwt` wallet-session byte-identical regression + agent HDKD-omni tag.
+- `cargo test -p agentkeys-cli -p agentkeys-daemon` — compile + existing suites (note: `k11::tests::enroll_writes_file_with_strict_perms` is a pre-existing parallel-execution flake — passes in isolation; unrelated to #144).
+- End-to-end: `bash harness/phase1-wire-demo.sh --real --webauthn` — Phase P uses the real broker code + daemon redeem + master bind/grant; assert 4.2 deterministic memory-inject stays green (STS relay tags the HDKD omni).
+
+## Out of scope (deferred)
+Broker chain-write / meta-tx; secret-keyed HDKD / frozen genesis seed; HDKD
+sub-actors; broker-side K11 verify (stays on-chain); production push transport
+(APNs/FCM) — the pending-binding data model + `pending-bindings` endpoint ship now.
diff --git a/harness/phase1-wire-demo.sh b/harness/phase1-wire-demo.sh
index b98698af..b403b002 100755
--- a/harness/phase1-wire-demo.sh
+++ b/harness/phase1-wire-demo.sh
@@ -230,6 +230,9 @@ resolve_sbx_paths() {
   [[ -n "$SBX_HOME" ]] || { fail "1.0 sandbox home" "could not resolve \$HOME in the sandbox"; return 1; }
   AGENT_BIN_DST="$SBX_HOME/.local/bin/agentkeys"
   MCP_BIN_DST="$SBX_HOME/.local/bin/agentkeys-mcp-server"
+  # §10.2 agent bootstrap (issue #144): the daemon's --init-link-code one-shot
+  # generates K10 + redeems the master link code IN THE SANDBOX (Phase P.1).
+  DAEMON_BIN_DST="$SBX_HOME/.local/bin/agentkeys-daemon"
   sbx_exec "mkdir -p \"$SBX_HOME/.local/bin\"" >/dev/null
 }
 
@@ -456,7 +459,8 @@ phase1_sandbox() {
   build_linux_binaries || return
   local mcp_bin_changed=false
   for pair in "$LINUX_TARGET_DIR/release/agentkeys:$AGENT_BIN_DST" \
-              "$LINUX_TARGET_DIR/release/agentkeys-mcp-server:$MCP_BIN_DST"; do
+              "$LINUX_TARGET_DIR/release/agentkeys-mcp-server:$MCP_BIN_DST" \
+              "$LINUX_TARGET_DIR/release/agentkeys-daemon:$DAEMON_BIN_DST"; do
     local src="${pair%%:*}" dst="${pair##*:}"
     local name; name="$(basename "$dst")"
     local want; want="$(shasum -a256 "$src" 2>/dev/null | awk '{print $1}')"
@@ -476,46 +480,72 @@ phase1_sandbox() {
   done
 
   # ─── Phase P — install (pair) ────────────────────────────────────────────────
-  # Fresh §10.2 pairing: the agent generates its OWN secp256k1 device key IN THE
-  # SANDBOX (never on the master), mints a session via wallet_sig, the master
-  # binds the device on-chain, then "approves" the memory scope. Fresh each run
-  # (--regen) → new omni → empty memory → seeded at 1.5 → recalled in Act 1: the
-  # full "install an app + approve its permissions" story. Skipped under
-  # --reuse-agent (legacy master-side agent key) and in --light.
+  # Fresh §10.2 HDKD pairing (issue #144) — the "install an app + approve its
+  # permissions" story, four steps:
+  #   P.0 create  — the MASTER mints a one-time link code bound to the HDKD child
+  #                 omni  O_agent = SHA256(.. || O_master || "//label")  (real
+  #                 broker /v1/agent/create; replaces the old openssl stub).
+  #   P.1 install — the AGENT generates its OWN K10 device key IN THE SANDBOX (the
+  #                 daemon's --init-link-code one-shot; key never on the master),
+  #                 proves possession, redeems the code → J1_agent + binding artifact.
+  #   P.2 bind    — the MASTER submits registerAgentDevice (no biometric).
+  #   P.3 grant   — the MASTER grants the requested scope (one Touch ID).
+  # P.2+P.3 are ONE product approval conceptually; kept as two steps so the test
+  # drives + verifies each deterministically. Skipped under --reuse-agent + --light.
   if [[ "$MODE" == "real" && "$REUSE_AGENT" != true ]]; then
-    log "  Phase P — install (pair): agent generates its device key IN THE SANDBOX (arch.md §10.2; interim #144)"
-    local link_code ds ds_addr ds_actor ds_dkh ds_pop ds_jwt
-    link_code="lc-$(openssl rand -hex 16)"   # one-time link code (master-minted; stub binding per #144)
-    ds="$(sbx_exec "$AGENT_BIN_DST agent device-session --broker-url ${BROKER_URL:-} --link-code $link_code --regen 2>&1")"
-    ds_addr="$(echo "$ds" | jq -r '.agent_address // empty' 2>/dev/null)"
-    ds_actor="$(echo "$ds" | jq -r '.actor_omni // empty' 2>/dev/null)"
-    ds_dkh="$(echo "$ds" | jq -r '.device_key_hash // empty' 2>/dev/null)"
-    ds_pop="$(echo "$ds" | jq -r '.pop_sig // empty' 2>/dev/null)"
-    ds_jwt="$(echo "$ds" | jq -r '.session_jwt // empty' 2>/dev/null)"
-    if [[ -z "$ds_jwt" || -z "$ds_actor" || -z "$ds_addr" || -z "$ds_dkh" || -z "$ds_pop" ]]; then
-      fail "P.1 device-session" "in-sandbox device-session failed: $(echo "$ds" | tr '\n' ' ' | cut -c1-200)"
+    log "  Phase P — install (pair): §10.2 HDKD bootstrap (issue #144)"
+    if [[ -z "$SESSION_BEARER" ]]; then
+      fail "P.0 create" "no operator session bearer (0.7) — cannot mint a link code"
     else
-      ACTOR_OMNI="$ds_actor"; AGENT_SESSION_BEARER="$ds_jwt"; DEVICE_KEY_HASH="$ds_dkh"
-      ok "P.1 device-session" "📲 agent paired — addr ${ds_addr:0:12}…, omni ${ds_actor:0:14}… (key SANDBOX-only)"
-      # P.2 master binds the SANDBOX-generated device on-chain (it never saw the key).
-      local reg; reg="$(bash "$REPO_ROOT/scripts/heima-agent-create.sh" --label "$AGENT_LABEL" \
-        --agent-address "$ds_addr" --actor-omni "$ds_actor" --device-key-hash "$ds_dkh" --pop-sig "$ds_pop" 2>&1)"
-      echo "$reg" | sed 's/^/        /' >&2
-      if echo "$reg" | grep -qiE '"ok"[[:space:]]*:[[:space:]]*true'; then
-        ok "P.2 register device" "on-chain registerAgentDevice (or already-active)"
+      # P.0 master mints a real one-time link code bound to the child omni.
+      local cr link_code child_omni
+      cr="$(curl -sS --max-time 30 -X POST "${BROKER_URL%/}/v1/agent/create" \
+        -H "authorization: Bearer $SESSION_BEARER" -H 'content-type: application/json' \
+        -d "$(jq -n --arg label "$AGENT_LABEL" --arg scope "${SEED_SCOPE_SERVICES:-memory}" '{label:$label, requested_scope:$scope}')" 2>&1)"
+      link_code="$(echo "$cr" | jq -r '.link_code // empty' 2>/dev/null)"
+      child_omni="$(echo "$cr" | jq -r '.child_omni // empty' 2>/dev/null)"
+      if [[ -z "$link_code" || -z "$child_omni" ]]; then
+        fail "P.0 create" "agent/create returned no link code: $(echo "$cr" | tr '\n' ' ' | cut -c1-200)"
       else
-        fail "P.2 register device" "registerAgentDevice failed: $(echo "$reg" | tr '\n' ' ' | cut -c1-160)"
-      fi
-      # P.3 approve permissions: master grants the FRESH actor the memory scope.
-      if [[ "$WEBAUTHN" == true ]]; then
-        log "    P.3 approve permissions: heima-scope-set --webauthn --agent $AGENT_LABEL --services ${SEED_SCOPE_SERVICES:-memory} (expect Touch ID)"
-        local grant; grant="$(bash "$REPO_ROOT/scripts/heima-scope-set.sh" --webauthn --agent "$AGENT_LABEL" --services "${SEED_SCOPE_SERVICES:-memory}" 2>&1)"
-        echo "$grant" | sed 's/^/        /' >&2
-        echo "$grant" | grep -qiE '"ok"[[:space:]]*:[[:space:]]*true' \
-          && ok "P.3 approve permissions" "🔐 master granted [${SEED_SCOPE_SERVICES:-memory}] to ${ds_actor:0:14}… (Touch ID)" \
-          || fail "P.3 approve permissions" "scope grant failed: $(echo "$grant" | tr '\n' ' ' | cut -c1-160)"
-      else
-        skip "P.3 approve permissions" "no --webauthn — re-run with --real --webauthn so the master can grant the fresh actor's scope (Touch ID)"
+        ok "P.0 create" "📇 master minted link code → child omni ${child_omni:0:14}… (label $AGENT_LABEL)"
+        # P.1 agent generates K10 + redeems IN THE SANDBOX (daemon one-shot; key
+        # never on the master). 2>/dev/null drops the daemon's stderr logs so
+        # stdout is clean artifact JSON for jq.
+        local ds ds_addr ds_actor ds_dkh ds_pop ds_jwt
+        ds="$(sbx_exec "$DAEMON_BIN_DST --init-link-code $link_code --broker-url ${BROKER_URL:-} 2>/dev/null")"
+        ds_addr="$(echo "$ds" | jq -r '.agent_address // empty' 2>/dev/null)"
+        ds_actor="$(echo "$ds" | jq -r '.actor_omni // empty' 2>/dev/null)"
+        ds_dkh="$(echo "$ds" | jq -r '.device_key_hash // empty' 2>/dev/null)"
+        ds_pop="$(echo "$ds" | jq -r '.pop_sig // empty' 2>/dev/null)"
+        ds_jwt="$(echo "$ds" | jq -r '.session_jwt // empty' 2>/dev/null)"
+        if [[ -z "$ds_jwt" || -z "$ds_actor" || -z "$ds_addr" || -z "$ds_dkh" || -z "$ds_pop" ]]; then
+          fail "P.1 install" "in-sandbox daemon redeem failed: $(echo "$ds" | tr '\n' ' ' | cut -c1-200)"
+        elif [[ "$ds_actor" != "$child_omni" ]]; then
+          fail "P.1 install" "redeemed omni ${ds_actor:0:14}… != created child ${child_omni:0:14}… (broker/derivation mismatch)"
+        else
+          ACTOR_OMNI="$ds_actor"; AGENT_SESSION_BEARER="$ds_jwt"; DEVICE_KEY_HASH="$ds_dkh"
+          ok "P.1 install" "📲 agent redeemed in-sandbox — addr ${ds_addr:0:12}…, omni ${ds_actor:0:14}… (K10 SANDBOX-only, J1_agent minted)"
+          # P.2 master binds the SANDBOX-generated device on-chain (it never saw the key).
+          local reg; reg="$(bash "$REPO_ROOT/scripts/heima-agent-create.sh" --label "$AGENT_LABEL" \
+            --agent-address "$ds_addr" --actor-omni "$ds_actor" --device-key-hash "$ds_dkh" --pop-sig "$ds_pop" 2>&1)"
+          echo "$reg" | sed 's/^/        /' >&2
+          if echo "$reg" | grep -qiE '"ok"[[:space:]]*:[[:space:]]*true'; then
+            ok "P.2 bind" "on-chain registerAgentDevice (or already-active)"
+          else
+            fail "P.2 bind" "registerAgentDevice failed: $(echo "$reg" | tr '\n' ' ' | cut -c1-160)"
+          fi
+          # P.3 master grants the requested scope (one Touch ID).
+          if [[ "$WEBAUTHN" == true ]]; then
+            log "    P.3 grant: heima-scope-set --webauthn --agent $AGENT_LABEL --services ${SEED_SCOPE_SERVICES:-memory} (expect Touch ID)"
+            local grant; grant="$(bash "$REPO_ROOT/scripts/heima-scope-set.sh" --webauthn --agent "$AGENT_LABEL" --services "${SEED_SCOPE_SERVICES:-memory}" 2>&1)"
+            echo "$grant" | sed 's/^/        /' >&2
+            echo "$grant" | grep -qiE '"ok"[[:space:]]*:[[:space:]]*true' \
+              && ok "P.3 grant" "🔐 master granted [${SEED_SCOPE_SERVICES:-memory}] to ${ds_actor:0:14}… (Touch ID)" \
+              || fail "P.3 grant" "scope grant failed: $(echo "$grant" | tr '\n' ' ' | cut -c1-160)"
+          else
+            skip "P.3 grant" "no --webauthn — re-run with --real --webauthn so the master can grant the fresh actor's scope (Touch ID)"
+          fi
+        fi
       fi
     fi
   fi
@@ -719,12 +749,15 @@ DOCKERFILE
 build_linux_binaries() {
   local agent_bin="$LINUX_TARGET_DIR/release/agentkeys"
   local mcp_bin="$LINUX_TARGET_DIR/release/agentkeys-mcp-server"
-  # Idempotent + source-aware: skip when both binaries exist and no tracked
+  # §10.2 agent bootstrap (issue #144): the daemon does the in-sandbox
+  # keygen + link-code redeem (Phase P.1).
+  local daemon_bin="$LINUX_TARGET_DIR/release/agentkeys-daemon"
+  # Idempotent + source-aware: skip when ALL binaries exist and no tracked
   # source is newer; otherwise (re)build incrementally (caches persist).
-  # Check BOTH binaries against the source — a stale mcp-server must not be
-  # masked by an up-to-date cli (the two crates build + fail independently).
-  if [[ -x "$agent_bin" && -x "$mcp_bin" ]] \
-     && ! sources_newer "$agent_bin" && ! sources_newer "$mcp_bin"; then
+  # Check EVERY binary against the source — a stale one must not be masked by
+  # an up-to-date sibling (the crates build + fail independently).
+  if [[ -x "$agent_bin" && -x "$mcp_bin" && -x "$daemon_bin" ]] \
+     && ! sources_newer "$agent_bin" && ! sources_newer "$mcp_bin" && ! sources_newer "$daemon_bin"; then
     ok "1.3 linux build" "up-to-date (no source changes; cached)"; return 0
   fi
   if ! command -v docker >/dev/null 2>&1; then
@@ -748,12 +781,12 @@ build_linux_binaries() {
     -e CARGO_TARGET_DIR=/src/target/sandbox-linux \
     -e RUSTUP_TOOLCHAIN="$cross_toolchain" \
     "$BUILDER_IMAGE" \
-    cargo build --release -p agentkeys-cli -p agentkeys-mcp-server || build_rc=$?
+    cargo build --release -p agentkeys-cli -p agentkeys-mcp-server -p agentkeys-daemon || build_rc=$?
   # Check the BUILD EXIT CODE, not just file existence — a stale binary from a
   # prior build must not be mistaken for a fresh success (silent-failure trap).
-  if [[ "$build_rc" -eq 0 && -x "$agent_bin" && -x "$mcp_bin" ]]; then
+  if [[ "$build_rc" -eq 0 && -x "$agent_bin" && -x "$mcp_bin" && -x "$daemon_bin" ]]; then
     ok "1.3 linux build" "built aarch64-linux binaries (toolchain $cross_toolchain)"; return 0
-  elif [[ -x "$agent_bin" && -x "$mcp_bin" ]]; then
+  elif [[ -x "$agent_bin" && -x "$mcp_bin" && -x "$daemon_bin" ]]; then
     # A stale binary must NOT silently pass: the deterministic checks below
     # (4.2 inject, the new crypto + STS relay) would then verify OLD code and the
     # summary could read green while SOURCE CHANGES ARE NOT DEPLOYED. Fail by
diff --git a/scripts/setup-broker-host.sh b/scripts/setup-broker-host.sh
index f2aa5eda..6fa7d95b 100755
--- a/scripts/setup-broker-host.sh
+++ b/scripts/setup-broker-host.sh
@@ -669,6 +669,18 @@ if command -v nm >/dev/null 2>&1; then
     warn "nm sees 0 email-link symbols, but cargo claims the feature is on."
     warn "Continuing — the post-restart /healthz probe will catch any real boot failure."
   fi
+  # Issue #144: confirm the §10.2 agent-bootstrap surface is linked (link-code
+  # endpoints + store). WARN-only; the post-restart route smoke below is the
+  # authoritative runtime gate.
+  agent_symbols=$(nm "$REPO_ROOT/target/release/agentkeys-broker-server" 2>/dev/null \
+    | grep -cE "link_code_redeem|agent_create|pending_bindings|link_codes" \
+    || true)
+  if (( agent_symbols > 0 )); then
+    log "  nm sees $agent_symbols §10.2 agent-bootstrap symbol(s) — issue #144 code is linked in"
+  else
+    warn "nm sees 0 §10.2 agent-bootstrap symbols (issue #144). The binary may predate #144."
+    warn "Continuing — the post-restart /v1/agent/create route smoke will catch a stale binary."
+  fi
 else
   log "  (nm not installed — skipping symbol-table sanity check)"
 fi
@@ -1570,6 +1582,23 @@ probe_or_die() {
        fix: verify EC2 instance role has ses:SendEmail OR set BROKER_EMAIL_SENDER=stub"
 }
 probe_or_die broker  8091 agentkeys-broker
+
+# Issue #144 — §10.2 agent-bootstrap route smoke. A no-bearer POST to
+# /v1/agent/create MUST return 401 (route registered, rejects unauth), NOT 404
+# (a stale binary predating #144 has no such route). Deterministic — no operator
+# session / keygen needed — so it can't flake; it's the authoritative "is the
+# #144 code actually serving on this host" gate that the nm check above hints at.
+agent_create_code="$(curl -s -o /dev/null -w '%{http_code}' --max-time 5 \
+  -X POST -H 'content-type: application/json' -d '{"label":"smoke"}' \
+  "http://127.0.0.1:8091/v1/agent/create" 2>/dev/null || echo 000)"
+case "$agent_create_code" in
+  401) log "  §10.2 /v1/agent/create live (401 unauth as expected — issue #144 routes deployed)" ;;
+  404) die "POST /v1/agent/create → 404: the running broker binary predates issue #144 (§10.2 routes missing).
+   The build/install did not deploy the new code. Fix:
+     rm -rf $REPO_ROOT/target/release/agentkeys-broker-server && re-run this script (--clean forces a clean rebuild)." ;;
+  *)   warn "POST /v1/agent/create → HTTP $agent_create_code (expected 401). Route appears present; continuing (the /healthz probe already passed)." ;;
+esac
+
 probe_or_die backend 8090 agentkeys-backend
 probe_or_die signer  8092 agentkeys-signer
 if [[ "$WITH_WORKERS" == "yes" ]]; then

From f99b7a072d133390ec64cca17f7aceeb0da51382 Mon Sep 17 00:00:00 2001
From: Hanwen Cheng <heawen.cheng@gmail.com>
Date: Sun, 31 May 2026 16:36:53 +0800
Subject: [PATCH 02/23] =?UTF-8?q?docs(runbook):=20fold=20#144=20gaps=20int?=
 =?UTF-8?q?o=20operator-runbook-wire=20=E2=80=94=20broker-upgrade=20prereq?=
 =?UTF-8?q?=20+=20P.0=20in=20the=20install=20step?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Phase P rewrite landed in the prior commit; this closes the two gaps an
operator would hit: (1) a Real-mode prereq that the broker must be running the
issue-144 code (else Phase P P.0 agent create 404s — folds in the
setup-broker-host.sh --upgrade fix + the 401-not-404 deploy self-check), and
(2) P.0 (master mints the link code) in the install-step summary bullet.
---
 docs/operator-runbook-wire.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/operator-runbook-wire.md b/docs/operator-runbook-wire.md
index 98207e33..ce17111b 100644
--- a/docs/operator-runbook-wire.md
+++ b/docs/operator-runbook-wire.md
@@ -112,6 +112,7 @@ Note it puts the agent key back on the master; use only for quick loops.
 - **Hermes** in the sandbox — the harness installs it (guarded `curl|bash`) if absent; needs GitHub reachable.
 
 **Real mode only:**
+- **The broker must be running the issue-#144 code** — the §10.2 endpoints (`/v1/agent/create`, `/v1/auth/link-code/redeem`, `/v1/agent/pending-bindings`). If your broker predates #144, run `bash scripts/setup-broker-host.sh --upgrade` (or `--test --yes` for the test host) FIRST, or Phase P `P.0 create` fails with HTTP **404**. The deploy self-checks this — a no-bearer `POST /v1/agent/create` must return **401** (route live), not 404 (stale binary).
 - The `setup-heima.sh` account already created (master device registered + contracts deployed; the harness verifies, never rebuilds). `OPERATOR_OMNI` is derived from your master key (`OPERATOR_KEY_FILE`); the **agent** identity is generated fresh in the sandbox by Phase P (no pre-existing agent file needed in the default fresh-pairing mode).
 - An **operator session JWT** for cap-mint. The harness now mints this **automatically and non-interactively**: step `0.7` decodes the on-disk session, and if it's missing, expired, **or for the wrong operator** (its `agentkeys.omni_account` ≠ the agent's `operator_omni`), it SIWE-signs a fresh one with `OPERATOR_KEY_FILE` (default `~/.agentkeys/heima-deployer.key` — the master key whose broker omni == `operator_omni`) via the broker's `wallet_sig` plugin. Requires `cast` (Foundry) on PATH. **Note:** the old `alice` email session is a *different* omni and is no longer used for cap-mint — set `OPERATOR_KEY_FILE` to the master key for your operator if the default isn't it. (Pass `AGENTKEYS_SESSION_BEARER` to override entirely.)
 - **For real memory (S3) to work:** **Phase P** generates the agent's device key **in the sandbox** and redeems the master link code there (`agentkeys-daemon --init-link-code` → `J1_agent`); the MCP server uses that session for the per-actor STS relay (`mint-oidc-jwt` → `AssumeRoleWithWebIdentity` → `X-Aws-*` headers to the worker), so the agent key never touches the master. Needs the per-data-class role ARNs (`MEMORY_ROLE_ARN`/`VAULT_ROLE_ARN`, from `operator-workstation.env`). Without the relay the worker falls back to its instance profile (no S3) and memory ops 502. (`--reuse-agent` instead mints the session on the master from `agent_private_key` in the agent file — legacy.)
@@ -121,7 +122,7 @@ Note it puts the agent key back on the master; use only for quick loops.
 ## The manual gates (the "test through" essence)
 
 - **LLM key** — auto from `OPENROUTER_API_KEY` (or `LLM_API_KEY`); only prompts if absent. Phase 4.0 writes it to the sandbox `~/.hermes/.env` and sets `provider: openrouter` + `model.default` (default `deepseek/deepseek-v4-flash`; override `LLM_MODEL`). A non-fatal `4.1 model smoke` confirms the model is live before the surprise.
-- **Install (pair)** — `--real` only: **Phase P** generates the agent's device key **in the sandbox** (`P.1`), the master binds it on-chain (`P.2`), and — with `--webauthn` — the master **approves** the agent's memory scope via Touch ID (`P.3`). Because every run pairs a **fresh** identity, this happens once per run. `--reuse-agent` skips it.
+- **Install (pair)** — `--real` only: **Phase P** — the master mints a one-time link code (`P.0`), the agent daemon (`agentkeys-daemon --init-link-code`) generates its device key **in the sandbox** + redeems it (`P.1`), the master binds it on-chain (`P.2`), and — with `--webauthn` — the master **approves** the agent's memory scope via Touch ID (`P.3`). Because every run pairs a **fresh** identity, this happens once per run. `--reuse-agent` skips it.
 - **Real Touch ID** — in real mode with `--webauthn`: **Phase P (P.3)** grants the freshly-paired agent's memory scope via `heima-scope-set.sh --webauthn`. The banner prints `webauthn=<flag>` so you know upfront whether a Touch ID ceremony will run. It's a hardware prompt — `--yes` does NOT bypass it (it only auto-confirms the software "proceed?" gates). Without `--webauthn`, `P.3` is skipped (the agent won't be able to read memory) — re-run with `--real --webauthn`.
 - **Seed the real memory worker** (`--real` only) — after pairing, step **1.5** writes the Chengdu fixture into the fresh actor's namespace (a brand-new identity always starts empty). Override `SEED_MEMORY_CONTENT` / `SEED_SCOPE_SERVICES` (the latter is the service set Phase P grants — it **sets** the full list).
 - **The Hermes surprise** — open Hermes in the sandbox, send "where am I going this weekend?", and judge the memory-aware reply (`[y/N]`).

From fc969bf250d017cbfcd0de43f10c605fc8bccb1c Mon Sep 17 00:00:00 2001
From: Hanwen Cheng <heawen.cheng@gmail.com>
Date: Sun, 31 May 2026 16:50:39 +0800
Subject: [PATCH 03/23] feat(#144): drive the shipped CLI in the demo +
 complete the rendezvous (idempotent)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- demo (harness Phase P): P.0 now drives the agentkeys agent create CLI (was raw
  curl); P.1b drives agentkeys agent pending (the master-pull rendezvous); P.2
  acks the broker after binding so pending self-cleans. Falls back to a raw POST
  only when no local host binary exists.
- broker: new POST /v1/agent/pending-bindings/ack (J1_master-gated, operator-scoped
  mark_bound). The rendezvous never cleared before (bound_at was never set), so
  pending listed redeemed agents forever; the ack fixes that AND makes the list
  idempotent. agent_bootstrap_flow now asserts pending=1 then ack then pending=0.
- idempotency: AGENT_LABEL stays stable (deterministic HDKD omni) and the K10 file
  persists in the long-lived sandbox (clean_slate never wipes ~/.agentkeys), so
  registerAgentDevice hits already-registered, scope re-set + seed overwrite are
  no-ops, and the ack keeps pending clean — re-runs converge.
- docs: arch.md route list + 10.2 ack step; runbook Phase P (P.1b + ack + stable-label note).

broker 179 lib + agent_bootstrap_flow (incl. ack) green; clippy -D warnings clean.
---
 .../src/handlers/agent/pending.rs             | 30 +++++++++
 crates/agentkeys-broker-server/src/lib.rs     |  4 ++
 .../src/storage/link_codes.rs                 | 28 ++++++---
 .../tests/agent_bootstrap_flow.rs             | 36 +++++++++++
 docs/arch.md                                  |  8 ++-
 docs/operator-runbook-wire.md                 |  3 +-
 harness/phase1-wire-demo.sh                   | 63 +++++++++++++++----
 7 files changed, 151 insertions(+), 21 deletions(-)

diff --git a/crates/agentkeys-broker-server/src/handlers/agent/pending.rs b/crates/agentkeys-broker-server/src/handlers/agent/pending.rs
index 116de32d..9767cb4f 100644
--- a/crates/agentkeys-broker-server/src/handlers/agent/pending.rs
+++ b/crates/agentkeys-broker-server/src/handlers/agent/pending.rs
@@ -9,9 +9,11 @@
 //! pre-computed so the master can submit `registerAgentDevice` without recomputing.
 
 use axum::{extract::State, http::HeaderMap, http::StatusCode, response::IntoResponse, Json};
+use serde::Deserialize;
 use serde_json::json;
 
 use crate::error::BrokerError;
+use crate::handlers::agent::unix_now;
 use crate::handlers::grant::require_session_jwt;
 use crate::state::SharedState;
 
@@ -47,3 +49,31 @@ pub async fn pending_bindings(
 
     Ok((StatusCode::OK, Json(json!({ "pending": pending }))))
 }
+
+#[derive(Debug, Deserialize)]
+pub struct AckBody {
+    /// The link code whose redeemed binding the master just submitted on chain.
+    pub link_code: String,
+}
+
+/// `POST /v1/agent/pending-bindings/ack` — the master acks that it submitted
+/// `registerAgentDevice` for this binding, so it drops out of the pending list
+/// (issue #144). Without this the rendezvous would never clear — every redeemed
+/// agent would show as "pending" forever even after it's bound on chain. Scoped
+/// to the master's omni; idempotent (a second ack is a no-op → `acked: false`).
+pub async fn ack_binding(
+    State(state): State<SharedState>,
+    headers: HeaderMap,
+    Json(body): Json<AckBody>,
+) -> Result<impl IntoResponse, BrokerError> {
+    let session = require_session_jwt(&headers, &state)?;
+    let master_omni = session.agentkeys.omni_account;
+    let now = unix_now()?;
+    let updated = state
+        .link_code_store
+        .mark_bound(&body.link_code, &master_omni, now)?;
+    Ok((
+        StatusCode::OK,
+        Json(json!({ "acked": updated > 0, "link_code": body.link_code })),
+    ))
+}
diff --git a/crates/agentkeys-broker-server/src/lib.rs b/crates/agentkeys-broker-server/src/lib.rs
index 6dae7864..833508bd 100644
--- a/crates/agentkeys-broker-server/src/lib.rs
+++ b/crates/agentkeys-broker-server/src/lib.rs
@@ -77,6 +77,10 @@ pub fn create_router(state: SharedState) -> Router {
             "/v1/agent/pending-bindings",
             get(handlers::agent::pending::pending_bindings),
         )
+        .route(
+            "/v1/agent/pending-bindings/ack",
+            post(handlers::agent::pending::ack_binding),
+        )
         // Phase B grant endpoints (US-026).
         .route(
             "/v1/grant/create",
diff --git a/crates/agentkeys-broker-server/src/storage/link_codes.rs b/crates/agentkeys-broker-server/src/storage/link_codes.rs
index bda4705b..3faf18d0 100644
--- a/crates/agentkeys-broker-server/src/storage/link_codes.rs
+++ b/crates/agentkeys-broker-server/src/storage/link_codes.rs
@@ -255,15 +255,23 @@ impl LinkCodeStore {
         Ok(out)
     }
 
-    /// Mark a redeemed row as bound (master acked the on-chain submit). Idempotent
-    /// — a second ack is a no-op. Returns the matched/updated row count.
-    pub fn mark_bound(&self, link_code: &str, now: i64) -> BrokerResult<usize> {
+    /// Mark a redeemed row as bound (the master acked its on-chain submit), so
+    /// it drops out of [`pending_bindings`]. Scoped to `operator_omni` — an
+    /// operator can only ack its own bindings. Idempotent: a second ack matches
+    /// nothing. Returns the updated row count (1 = acked, 0 = unknown/already-bound).
+    pub fn mark_bound(
+        &self,
+        link_code: &str,
+        operator_omni: &str,
+        now: i64,
+    ) -> BrokerResult<usize> {
         let conn = self.lock()?;
         let n = conn
             .execute(
                 "UPDATE link_codes SET bound_at = ?1
-                 WHERE link_code = ?2 AND consumed_at IS NOT NULL AND bound_at IS NULL",
-                params![now, link_code],
+                 WHERE link_code = ?2 AND operator_omni = ?3
+                   AND consumed_at IS NOT NULL AND bound_at IS NULL",
+                params![now, link_code, operator_omni],
             )
             .map_err(|e| BrokerError::Internal(format!("mark_bound link_code: {e}")))?;
         Ok(n)
@@ -381,10 +389,16 @@ mod tests {
             .unwrap();
         s.consume("lc-1", "0xdevA", "0xpopA", 200).unwrap();
         assert_eq!(s.pending_bindings("op").unwrap().len(), 1);
-        assert_eq!(s.mark_bound("lc-1", 300).unwrap(), 1);
+        assert_eq!(s.mark_bound("lc-1", "op", 300).unwrap(), 1);
         assert!(s.pending_bindings("op").unwrap().is_empty());
         // Idempotent: a second ack matches nothing.
-        assert_eq!(s.mark_bound("lc-1", 400).unwrap(), 0);
+        assert_eq!(s.mark_bound("lc-1", "op", 400).unwrap(), 0);
+        // Operator-scoped: a different operator cannot ack this binding.
+        s.issue("lc-2", "childZ", "op", "agent-z", "memory", 100, 700)
+            .unwrap();
+        s.consume("lc-2", "0xdevZ", "0xpopZ", 200).unwrap();
+        assert_eq!(s.mark_bound("lc-2", "other-op", 300).unwrap(), 0);
+        assert_eq!(s.pending_bindings("op").unwrap().len(), 1);
     }
 
     #[test]
diff --git a/crates/agentkeys-broker-server/tests/agent_bootstrap_flow.rs b/crates/agentkeys-broker-server/tests/agent_bootstrap_flow.rs
index 6b8fad14..7e2d0816 100644
--- a/crates/agentkeys-broker-server/tests/agent_bootstrap_flow.rs
+++ b/crates/agentkeys-broker-server/tests/agent_bootstrap_flow.rs
@@ -234,6 +234,42 @@ async fn full_create_redeem_pending_flow() {
         .unwrap()
         .starts_with("0x"));
 
+    // ack the binding (master submitted registerAgentDevice) → the rendezvous
+    // self-cleans, so a re-run sees an empty pending list (idempotent).
+    let ack: Value = client
+        .post(format!("{}/v1/agent/pending-bindings/ack", broker_url))
+        .header("Authorization", format!("Bearer {bearer}"))
+        .json(&json!({ "link_code": link_code }))
+        .send()
+        .await
+        .unwrap()
+        .json()
+        .await
+        .unwrap();
+    assert_eq!(ack["acked"], true);
+    let pending2: Value = client
+        .get(format!("{}/v1/agent/pending-bindings", broker_url))
+        .header("Authorization", format!("Bearer {bearer}"))
+        .send()
+        .await
+        .unwrap()
+        .json()
+        .await
+        .unwrap();
+    assert_eq!(pending2["pending"].as_array().unwrap().len(), 0);
+    // Second ack is idempotent (already bound → acked:false).
+    let ack2: Value = client
+        .post(format!("{}/v1/agent/pending-bindings/ack", broker_url))
+        .header("Authorization", format!("Bearer {bearer}"))
+        .json(&json!({ "link_code": link_code }))
+        .send()
+        .await
+        .unwrap()
+        .json()
+        .await
+        .unwrap();
+    assert_eq!(ack2["acked"], false);
+
     // single-use: a second redeem of the same code is rejected.
     let replay = client
         .post(format!("{}/v1/auth/link-code/redeem", broker_url))
diff --git a/docs/arch.md b/docs/arch.md
index fff94b09..09463086 100644
--- a/docs/arch.md
+++ b/docs/arch.md
@@ -518,7 +518,10 @@ MASTER APPROVAL (async; master ≠ agent machine — the iOS/Android "first laun
     - AgentKeysScope.setScopeWithWebauthn(... requested_scope ...)  [the K11 gesture]
     The CLI exposes these as two deterministic steps (test automation); the
     operator experiences one approval. Install + permissions = one gesture.
-12. Agent's J1_agent now has scope; cap-mint works (§12).
+12. Master acks the binding (POST /v1/agent/pending-bindings/ack) → the broker
+    marks it bound so it drops out of the pending list (the rendezvous self-cleans;
+    re-bootstraps are idempotent).
+13. Agent's J1_agent now has scope; cap-mint works (§12).
 ```
 
 **Trust chain:** `master human → master K11 (at the approval) → master J1 + master-submitted on-chain binding → agent K10 binding`. The agent never holds K11 or any user-presence credential; the K11 gesture is the master's, exercised at step 11 (binding + scope), not at the broker.
@@ -781,7 +784,8 @@ The broker is the cap-mint authority. It does NOT hold credentials, K3, or any c
 /v1/auth/bind/<request_id>                    — WebAuthn enrollment (stage 2)
 /v1/auth/link-code/redeem                     — agent redeems link code → J1_agent (§10.2; no bearer, pop_sig-gated)
 /v1/agent/create                              — mint agent link-code (J1_master-gated; K11 NOT at broker — §10.2)
-/v1/agent/pending-bindings                    — master pulls redeemed-but-unbound agents to approve (§10.2)
+/v1/agent/pending-bindings                    — master pulls redeemed-but-unbound agents to approve (§10.2; GET)
+/v1/agent/pending-bindings/ack                — master acks an on-chain binding → clears it from pending (§10.2; POST, J1_master)
 /v1/wallet/link                               — link wallet to identity (post-derive, pre-SIWE)
 /v1/wallet/device/rotate                      — K10 rotation (§10.3.2; K11 required)
 /v1/cap/cred-fetch                            — cap-mint for credential fetch
diff --git a/docs/operator-runbook-wire.md b/docs/operator-runbook-wire.md
index ce17111b..b0b42ffc 100644
--- a/docs/operator-runbook-wire.md
+++ b/docs/operator-runbook-wire.md
@@ -61,7 +61,8 @@ story. Each run does a **fresh pairing** (a brand-new agent identity), so expect
    - **Phase P — install (pair)** 📲 (full §10.2 HDKD bootstrap, issue #144)
      - `P.0` the **master** mints a one-time link code bound to the HDKD child omni `O_agent = SHA256(.. ‖ O_master ‖ "//label")` (real broker `/v1/agent/create`; no more `openssl` stub).
      - `P.1` the **agent daemon** (`agentkeys-daemon --init-link-code`) generates its **own K10 device key in the sandbox**, proves possession, and **redeems** the code → `J1_agent` (the key never touches the master).
-     - `P.2` the master **binds** that device **on-chain** (`registerAgentDevice`, no biometric).
+     - `P.1b` the master pulls the rendezvous (`agentkeys agent pending`) and sees this agent awaiting approval.
+     - `P.2` the master **binds** that device **on-chain** (`registerAgentDevice`, no biometric) and **acks** the broker so it clears from `pending` (self-cleaning → idempotent re-runs).
      - `P.3` **🔐 Touch ID** — the master **grants** the agent's `[memory]` permission (`setScopeWithWebauthn`). Conceptually `P.2`+`P.3` are **one approval** (install + permissions, iOS/Android-style); kept as two steps for deterministic test automation.
    - **1.4–1.5** — MCP server (per-actor STS relay) starts; the fresh actor's memory is seeded (new identity ⇒ empty ⇒ seeds "Chengdu trip").
    - **Phase 2** — `agentkeys wire hermes` installs the IAM-gate hooks.
diff --git a/harness/phase1-wire-demo.sh b/harness/phase1-wire-demo.sh
index b403b002..6d7140f1 100755
--- a/harness/phase1-wire-demo.sh
+++ b/harness/phase1-wire-demo.sh
@@ -488,20 +488,43 @@ phase1_sandbox() {
   #   P.1 install — the AGENT generates its OWN K10 device key IN THE SANDBOX (the
   #                 daemon's --init-link-code one-shot; key never on the master),
   #                 proves possession, redeems the code → J1_agent + binding artifact.
-  #   P.2 bind    — the MASTER submits registerAgentDevice (no biometric).
+  #   P.1b pending— the MASTER pulls the rendezvous (`agentkeys agent pending`) and
+  #                 sees this agent awaiting approval.
+  #   P.2 bind    — the MASTER submits registerAgentDevice (no biometric) + acks the
+  #                 broker (clears the binding from pending).
   #   P.3 grant   — the MASTER grants the requested scope (one Touch ID).
   # P.2+P.3 are ONE product approval conceptually; kept as two steps so the test
   # drives + verifies each deterministically. Skipped under --reuse-agent + --light.
+  #
+  # IDEMPOTENT: AGENT_LABEL (default `demo-agent`) is stable, and the child omni is
+  # a deterministic HDKD of (O_master, label), so re-runs converge — the K10 file
+  # persists in the long-lived sandbox (clean_slate never wipes ~/.agentkeys), so
+  # registerAgentDevice hits the already-registered skip, the scope grant re-sets
+  # the same scope, the seed (1.5) overwrites, and the ack keeps `agent pending`
+  # self-cleaning. (Set AGENT_LABEL=demo-agent-$(date +%s) for a brand-new omni.)
   if [[ "$MODE" == "real" && "$REUSE_AGENT" != true ]]; then
     log "  Phase P — install (pair): §10.2 HDKD bootstrap (issue #144)"
     if [[ -z "$SESSION_BEARER" ]]; then
       fail "P.0 create" "no operator session bearer (0.7) — cannot mint a link code"
     else
-      # P.0 master mints a real one-time link code bound to the child omni.
-      local cr link_code child_omni
-      cr="$(curl -sS --max-time 30 -X POST "${BROKER_URL%/}/v1/agent/create" \
-        -H "authorization: Bearer $SESSION_BEARER" -H 'content-type: application/json' \
-        -d "$(jq -n --arg label "$AGENT_LABEL" --arg scope "${SEED_SCOPE_SERVICES:-memory}" '{label:$label, requested_scope:$scope}')" 2>&1)"
+      # P.0 master mints a real one-time link code bound to the child omni via the
+      # `agentkeys agent create` CLI (the operator command we ship). Resolve a LOCAL
+      # host binary (same release→debug→PATH order as the chain helpers); fall back
+      # to a raw broker POST only if no local binary exists, so a --real run without
+      # a host build still works.
+      local cr link_code child_omni la
+      if [[ -x "$REPO_ROOT/target/release/agentkeys" ]]; then la="$REPO_ROOT/target/release/agentkeys"
+      elif [[ -x "$REPO_ROOT/target/debug/agentkeys" ]]; then la="$REPO_ROOT/target/debug/agentkeys"
+      else la="$(command -v agentkeys 2>/dev/null || true)"; fi
+      if [[ -n "$la" ]]; then
+        cr="$("$la" agent create --label "$AGENT_LABEL" --services "${SEED_SCOPE_SERVICES:-memory}" \
+          --broker-url "${BROKER_URL%/}" --session-bearer "$SESSION_BEARER" 2>&1)"
+      else
+        log "    P.0 create: no local agentkeys binary — raw POST fallback (build the host CLI to exercise it: cargo build --release -p agentkeys-cli)"
+        cr="$(curl -sS --max-time 30 -X POST "${BROKER_URL%/}/v1/agent/create" \
+          -H "authorization: Bearer $SESSION_BEARER" -H 'content-type: application/json' \
+          -d "$(jq -n --arg label "$AGENT_LABEL" --arg scope "${SEED_SCOPE_SERVICES:-memory}" '{label:$label, requested_scope:$scope}')" 2>&1)"
+      fi
       link_code="$(echo "$cr" | jq -r '.link_code // empty' 2>/dev/null)"
       child_omni="$(echo "$cr" | jq -r '.child_omni // empty' 2>/dev/null)"
       if [[ -z "$link_code" || -z "$child_omni" ]]; then
@@ -525,12 +548,29 @@ phase1_sandbox() {
         else
           ACTOR_OMNI="$ds_actor"; AGENT_SESSION_BEARER="$ds_jwt"; DEVICE_KEY_HASH="$ds_dkh"
           ok "P.1 install" "📲 agent redeemed in-sandbox — addr ${ds_addr:0:12}…, omni ${ds_actor:0:14}… (K10 SANDBOX-only, J1_agent minted)"
+          # P.1b master pulls the pending binding via `agentkeys agent pending` (the
+          # rendezvous we built) and confirms THIS agent is awaiting approval.
+          # Read-only + idempotent; best-effort (needs the local CLI).
+          if [[ -n "$la" ]]; then
+            local pend; pend="$("$la" agent pending --broker-url "${BROKER_URL%/}" --session-bearer "$SESSION_BEARER" 2>&1)"
+            if echo "$pend" | jq -e --arg c "$ds_actor" '.pending[]? | select(.child_omni==$c)' >/dev/null 2>&1; then
+              ok "P.1b pending" "🔔 master sees agent ${ds_actor:0:14}… awaiting approval (agent pending)"
+            else
+              skip "P.1b pending" "agent pending did not list ${ds_actor:0:14}… (non-fatal): $(echo "$pend" | tr '\n' ' ' | cut -c1-120)"
+            fi
+          fi
           # P.2 master binds the SANDBOX-generated device on-chain (it never saw the key).
           local reg; reg="$(bash "$REPO_ROOT/scripts/heima-agent-create.sh" --label "$AGENT_LABEL" \
             --agent-address "$ds_addr" --actor-omni "$ds_actor" --device-key-hash "$ds_dkh" --pop-sig "$ds_pop" 2>&1)"
           echo "$reg" | sed 's/^/        /' >&2
           if echo "$reg" | grep -qiE '"ok"[[:space:]]*:[[:space:]]*true'; then
             ok "P.2 bind" "on-chain registerAgentDevice (or already-active)"
+            # Ack the rendezvous: tell the broker the master bound this device so it
+            # drops out of pending-bindings (self-cleaning → idempotent re-runs).
+            curl -sS --max-time 15 -X POST "${BROKER_URL%/}/v1/agent/pending-bindings/ack" \
+              -H "authorization: Bearer $SESSION_BEARER" -H 'content-type: application/json' \
+              -d "$(jq -n --arg lc "$link_code" '{link_code:$lc}')" >/dev/null 2>&1 \
+              && log "    P.2 ack: binding acked — cleared from pending (idempotent)" || true
           else
             fail "P.2 bind" "registerAgentDevice failed: $(echo "$reg" | tr '\n' ' ' | cut -c1-160)"
           fi
@@ -626,11 +666,12 @@ phase1_sandbox() {
     # block on read_to_string(stdin) without it (fixed in hook.rs, kept here so
     # a stale on-sandbox binary can't re-freeze the demo before 1.3 re-uploads).
     if [[ "$REUSE_AGENT" != true ]]; then
-      # Fresh pairing: Phase P just paired this brand-new actor and (with
-      # --webauthn) approved its [memory] scope at P.3 — you already gave Touch
-      # ID there. A fresh actor's namespace is always empty. So SEED
-      # AUTOMATICALLY — no [y/N] gate, no second prompt, no second Touch ID. One
-      # memory.put, which succeeds because P.3 granted the scope.
+      # Fresh pairing: Phase P just paired this actor and (with --webauthn)
+      # approved its [memory] scope at P.3 — you already gave Touch ID there. The
+      # namespace is empty on the first run for this label and simply overwritten
+      # on idempotent re-runs (stable HDKD omni). So SEED AUTOMATICALLY — no [y/N]
+      # gate, no second prompt, no second Touch ID. One idempotent memory.put,
+      # which succeeds because P.3 granted the scope.
       local out; out="$(sbx_exec "$env_pfx $AGENT_BIN_DST memory put --namespace $MEMORY_NS --content \"$seed\" 2>&1")"
       if echo "$out" | grep -qiE '"ok":[[:space:]]*true|s3_key'; then
         ok "1.5 seed memory" "auto-seeded '$MEMORY_NS' (scope approved at Phase P — no extra prompt)"

From 3758261600c3239517d689716fe18bb16f714055 Mon Sep 17 00:00:00 2001
From: Hanwen Cheng <heawen.cheng@gmail.com>
Date: Sun, 31 May 2026 18:10:44 +0800
Subject: [PATCH 04/23] docs(runbook)+comment: drop no-op --upgrade from
 setup-broker-host.sh references

Per the CLAUDE.md never-pass---upgrade rule (it is a back-compat no-op; the
script is idempotent):
- operator-runbook-wire.md broker-version prereq: --ref main instead of --upgrade.
- setup-broker-host.sh: idempotency comment no longer illustrates with --upgrade.
---
 docs/operator-runbook-wire.md | 2 +-
 scripts/setup-broker-host.sh  | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/operator-runbook-wire.md b/docs/operator-runbook-wire.md
index b0b42ffc..383e53c2 100644
--- a/docs/operator-runbook-wire.md
+++ b/docs/operator-runbook-wire.md
@@ -113,7 +113,7 @@ Note it puts the agent key back on the master; use only for quick loops.
 - **Hermes** in the sandbox — the harness installs it (guarded `curl|bash`) if absent; needs GitHub reachable.
 
 **Real mode only:**
-- **The broker must be running the issue-#144 code** — the §10.2 endpoints (`/v1/agent/create`, `/v1/auth/link-code/redeem`, `/v1/agent/pending-bindings`). If your broker predates #144, run `bash scripts/setup-broker-host.sh --upgrade` (or `--test --yes` for the test host) FIRST, or Phase P `P.0 create` fails with HTTP **404**. The deploy self-checks this — a no-bearer `POST /v1/agent/create` must return **401** (route live), not 404 (stale binary).
+- **The broker must be running the issue-#144 code** — the §10.2 endpoints (`/v1/agent/create`, `/v1/auth/link-code/redeem`, `/v1/agent/pending-bindings`). If your broker predates #144, run `bash scripts/setup-broker-host.sh --ref main` (or `--test --yes` for the test host) FIRST, or Phase P `P.0 create` fails with HTTP **404**. The deploy self-checks this — a no-bearer `POST /v1/agent/create` must return **401** (route live), not 404 (stale binary).
 - The `setup-heima.sh` account already created (master device registered + contracts deployed; the harness verifies, never rebuilds). `OPERATOR_OMNI` is derived from your master key (`OPERATOR_KEY_FILE`); the **agent** identity is generated fresh in the sandbox by Phase P (no pre-existing agent file needed in the default fresh-pairing mode).
 - An **operator session JWT** for cap-mint. The harness now mints this **automatically and non-interactively**: step `0.7` decodes the on-disk session, and if it's missing, expired, **or for the wrong operator** (its `agentkeys.omni_account` ≠ the agent's `operator_omni`), it SIWE-signs a fresh one with `OPERATOR_KEY_FILE` (default `~/.agentkeys/heima-deployer.key` — the master key whose broker omni == `operator_omni`) via the broker's `wallet_sig` plugin. Requires `cast` (Foundry) on PATH. **Note:** the old `alice` email session is a *different* omni and is no longer used for cap-mint — set `OPERATOR_KEY_FILE` to the master key for your operator if the default isn't it. (Pass `AGENTKEYS_SESSION_BEARER` to override entirely.)
 - **For real memory (S3) to work:** **Phase P** generates the agent's device key **in the sandbox** and redeems the master link code there (`agentkeys-daemon --init-link-code` → `J1_agent`); the MCP server uses that session for the per-actor STS relay (`mint-oidc-jwt` → `AssumeRoleWithWebIdentity` → `X-Aws-*` headers to the worker), so the agent key never touches the master. Needs the per-data-class role ARNs (`MEMORY_ROLE_ARN`/`VAULT_ROLE_ARN`, from `operator-workstation.env`). Without the relay the worker falls back to its instance profile (no S3) and memory ops 502. (`--reuse-agent` instead mints the session on the master from `agent_private_key` in the agent file — legacy.)
diff --git a/scripts/setup-broker-host.sh b/scripts/setup-broker-host.sh
index 6fa7d95b..798d6373 100755
--- a/scripts/setup-broker-host.sh
+++ b/scripts/setup-broker-host.sh
@@ -827,7 +827,7 @@ fi
 #   2) deb fallback (older / non-snap images; service: amazon-ssm-agent.service)
 #
 # Both produce a unit named `amazon-ssm-agent` in our systemctl alias check
-# below, so subsequent `setup-broker-host.sh --upgrade` re-runs skip.
+# below, so subsequent `setup-broker-host.sh` re-runs skip.
 ssm_unit_active() {
   systemctl is-active snap.amazon-ssm-agent.amazon-ssm-agent.service >/dev/null 2>&1 \
     || systemctl is-active amazon-ssm-agent.service >/dev/null 2>&1

From 1a7bdab2d8d8f864b7b703039b00acd5d30bb7d7 Mon Sep 17 00:00:00 2001
From: Hanwen Cheng <heawen.cheng@gmail.com>
Date: Sun, 31 May 2026 18:03:12 +0800
Subject: [PATCH 05/23] fix(setup-cloud): self-heal the SSM precondition for
 step 15 (prod + test brokers)

setup-cloud.sh step 15 (SSM SendCommand to bring up the MCP server) assumed the
broker EC2 was already a registered SSM managed instance but never ensured it.
Operators hit `SendCommand -> InvalidInstanceId` because the broker-host role was
created WITHOUT AmazonSSMManagedInstanceCore, so the on-host amazon-ssm-agent
can't register. (And separately, a caller lacking ssm:SendCommand got a
misleading "does the instance have the agent?" message.)

- ensure_ssm_managed(): runs before SendCommand. Resolves the role from the
  INSTANCE's attached profile (naming-agnostic, so the SAME code fixes BOTH the
  prod `agentkeys-broker-host` and the test broker's own profile), idempotently
  attaches AmazonSSMManagedInstanceCore if missing, then polls
  describe-instance-information until PingStatus=Online. If the agent never
  registers (role now correct => the agent itself isn't running), it dies with
  the exact restart remediation (ssh-broker.sh + setup-broker-host.sh --upgrade,
  or reboot). Idempotent: a re-run with the policy already attached skips.
- SendCommand now captures stderr and distinguishes a CALLER ssm:SendCommand
  AccessDenied (identity-based policy gap) from a real instance problem, with a
  precise remediation (put-user-policy; see provision-ci-deploy-role.sh for the
  policy shape) instead of the misleading instance-agent message.
- aws iam calls are global (no --region); ec2/ssm reads pass --region "$REGION"
  per the agentkeys-admin-defaults-to-us-west-2 trap (CLAUDE.md).

Env-agnostic + idempotent: works for both broker envs and converges on re-run.
---
 scripts/setup-cloud.sh | 88 ++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 84 insertions(+), 4 deletions(-)

diff --git a/scripts/setup-cloud.sh b/scripts/setup-cloud.sh
index 37cb4546..04fd2777 100755
--- a/scripts/setup-cloud.sh
+++ b/scripts/setup-cloud.sh
@@ -697,10 +697,81 @@ do_step_14() {
   ok "mail bucket policy applied"
 }
 
+# Step-15 precondition: the broker EC2 must be a REGISTERED SSM managed instance
+# before SendCommand, or AWS returns InvalidInstanceId / "not in a valid state".
+# The on-host amazon-ssm-agent only registers if the instance's role carries
+# AmazonSSMManagedInstanceCore — and operators repeatedly hit this because the
+# broker-host role (prod `agentkeys-broker-host`; the test broker uses its own
+# profile) was created WITHOUT it. We self-heal idempotently, deriving the role
+# from the INSTANCE's actual attached profile so the SAME code fixes BOTH the
+# prod and test brokers regardless of role naming, then poll until the agent
+# registers. `aws iam` is global (no --region); ec2/ssm reads pass --region
+# "$REGION" per the agentkeys-admin-defaults-to-us-west-2 trap (CLAUDE.md).
+ensure_ssm_managed() {
+  local ssm_core="arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore"
+
+  # Resolve the role behind THIS instance's profile (naming-agnostic).
+  local prof_arn
+  prof_arn="$(aws --region "$REGION" ec2 describe-instances --instance-ids "$INSTANCE_ID" \
+    --query 'Reservations[0].Instances[0].IamInstanceProfile.Arn' --output text 2>/dev/null || true)"
+  if [ -z "$prof_arn" ] || [ "$prof_arn" = "None" ]; then
+    die "SSM precondition: $INSTANCE_ID has NO instance profile — it can never register with SSM. Attach one carrying AmazonSSMManagedInstanceCore (docs/cloud-bootstrap.md §6), then re-run."
+  fi
+  local prof_name role
+  prof_name="${prof_arn##*/}"
+  role="$(aws iam get-instance-profile --instance-profile-name "$prof_name" \
+    --query 'InstanceProfile.Roles[0].RoleName' --output text 2>/dev/null || true)"
+  if [ -z "$role" ] || [ "$role" = "None" ]; then
+    die "SSM precondition: instance profile $prof_name has no role attached — re-create it (docs/cloud-bootstrap.md §6)."
+  fi
+
+  # Idempotently ensure AmazonSSMManagedInstanceCore on that role.
+  local have
+  have="$(aws iam list-attached-role-policies --role-name "$role" \
+    --query "length(AttachedPolicies[?PolicyArn=='$ssm_core'])" --output text 2>/dev/null || echo 0)"
+  if [ "$have" = "1" ]; then
+    ok "SSM: AmazonSSMManagedInstanceCore already on $role"
+  elif [ "$DRY_RUN" = "1" ]; then
+    warn "DRY: would attach AmazonSSMManagedInstanceCore to $role (instance profile $prof_name)"
+  else
+    if aws iam attach-role-policy --role-name "$role" --policy-arn "$ssm_core" >/dev/null 2>&1; then
+      ok "SSM: attached AmazonSSMManagedInstanceCore to $role (idempotent)"
+    else
+      die "SSM: could not attach AmazonSSMManagedInstanceCore to $role — your caller needs iam:AttachRolePolicy (\`awsp agentkeys-admin\`)."
+    fi
+  fi
+  if [ "$DRY_RUN" = "1" ]; then return 0; fi
+
+  # Poll until the on-host agent registers (it refreshes IMDS creds, ~30s cadence;
+  # a freshly-attached policy is usually picked up within 1–2 min).
+  local ping="" i
+  for i in $(seq 1 18); do
+    ping="$(aws --region "$REGION" ssm describe-instance-information \
+      --filters "Key=InstanceIds,Values=$INSTANCE_ID" \
+      --query 'InstanceInformationList[0].PingStatus' --output text 2>/dev/null || true)"
+    if [ "$ping" = "Online" ]; then
+      ok "SSM: $INSTANCE_ID registered (PingStatus=Online)"
+      return 0
+    fi
+    if [ "$i" = "1" ]; then
+      printf "    waiting up to ~3min for %s to register with SSM (PingStatus=%s)…\n" "$INSTANCE_ID" "${ping:-none}" >&2
+    fi
+    sleep 10
+  done
+  die "SSM: $INSTANCE_ID never reached PingStatus=Online (last: ${ping:-none}) after ~3min. The role now carries AmazonSSMManagedInstanceCore, so the on-host amazon-ssm-agent likely isn't running. (Re)start it via the single entry point, then re-run this step:
+     bash scripts/ssh-broker.sh $([ "$TEST_MODE" = "1" ] && echo test || echo prod)
+     sudo bash /opt/agentkeys-src/scripts/setup-broker-host.sh --upgrade   # installs+enables the agent
+   or reboot (broker auto-restarts via systemd): aws --region $REGION ec2 reboot-instances --instance-ids $INSTANCE_ID"
+}
+
 do_step_15() {
   CUR_STEP=15; step "Bring up agentkeys-mcp-server on broker (via SSM)"
   : "${INSTANCE_ID:?INSTANCE_ID missing — broker EC2 needs to exist (re-run step 4 first)}"
 
+  # Make the broker EC2 SSM-ready BEFORE SendCommand (self-heals the missing
+  # AmazonSSMManagedInstanceCore that bit both prod + test brokers). Idempotent.
+  ensure_ssm_managed
+
   REPO_URL_FOR_MCP="${AGENTKEYS_REPO_URL:-https://github.com/litentry/agentKeys.git}"
   REV_FOR_MCP="${AGENTKEYS_REV:-main}"
   MCP_HOST_FLAGS=""
@@ -744,15 +815,24 @@ sudo -E AGENTKEYS_REPO_URL=${REPO_URL_FOR_MCP} AGENTKEYS_REV=${REV_FOR_MCP} \\
 EOSH
 )
 
-  local cmd_id
-  cmd_id=$(aws ssm send-command \
+  local cmd_id _send_err
+  _send_err="$(mktemp)"
+  if ! cmd_id=$(aws ssm send-command \
     --region "$REGION" \
     --instance-ids "$INSTANCE_ID" \
     --document-name "AWS-RunShellScript" \
     --comment "agentkeys-mcp-server bring-up ($([ "$TEST_MODE" = "1" ] && echo test || echo prod))" \
     --parameters "{\"commands\": $(jq -Rs . <<<"$mcp_bring_up_script" | jq -s .)}" \
-    --query "Command.CommandId" --output text) \
-    || die "aws ssm send-command failed — does $INSTANCE_ID have amazon-ssm-agent + the SSM instance profile?"
+    --query "Command.CommandId" --output text 2>"$_send_err"); then
+    local _err; _err="$(cat "$_send_err" 2>/dev/null || true)"; rm -f "$_send_err"
+    # ensure_ssm_managed already verified the instance is registered, so a
+    # SendCommand AccessDenied here is a CALLER policy gap, not an instance one.
+    if printf '%s' "$_err" | grep -qiE 'accessdenied|not authorized|ssm:sendcommand'; then
+      die "ssm:SendCommand DENIED for your CALLER (identity-based policy gap — $INSTANCE_ID is SSM-registered, verified just above, so this is NOT an instance problem). Your operator IAM user needs ssm:SendCommand on the instance + the AWS-RunShellScript document, plus ssm:GetCommandInvocation/ListCommandInvocations. Grant it with \`aws iam put-user-policy\` on your user (see scripts/provision-ci-deploy-role.sh for the exact policy shape it grants the CI deploy role), then re-run. Detail: $_err"
+    fi
+    die "aws ssm send-command failed — does $INSTANCE_ID have amazon-ssm-agent + the SSM instance profile? Detail: $_err"
+  fi
+  rm -f "$_send_err"
   ok "SSM command $cmd_id queued on $INSTANCE_ID; polling for completion (max 10 min)"
 
   # Poll every 10s for up to 10 min. setup-mcp-host.sh is normally <3 min;

From bd62bc9d08463623430c61113f42e7ca75ebff94 Mon Sep 17 00:00:00 2001
From: Hanwen Cheng <heawen.cheng@gmail.com>
Date: Sun, 31 May 2026 18:10:32 +0800
Subject: [PATCH 06/23] fix(setup-cloud,docs): drop no-op --upgrade from
 setup-broker-host.sh refs + add CLAUDE.md rule

setup-broker-host.sh treats --upgrade (and --skip-pull) as back-compat NO-OPS
(it is idempotent + auto-detects bootstrap vs upgrade), so emitting it is
misleading. Replace active-path references with --ref main (the canonical
idempotent deploy invocation per CLAUDE.md) and codify the rule:
- setup-cloud.sh: ensure_ssm_managed remediation suggests --ref main.
- docs/ci-setup.md: prod-broker manual deploy uses --ref main.
- CLAUDE.md (Remote broker host): explicit never-pass---upgrade rule.
---
 CLAUDE.md              | 2 ++
 docs/ci-setup.md       | 2 +-
 scripts/setup-cloud.sh | 2 +-
 3 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 2f76ec6d..3d99fae8 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -90,6 +90,8 @@ Also: never gloss over a partial implementation in a demo doc or runbook. If the
 ## Remote broker host (single entry point)
 All remote-host changes (binary upgrades, systemd edits, nginx/certbot, env tweaks, mock-server redeploys) MUST go through `bash scripts/setup-broker-host.sh` — it's idempotent and auto-detects bootstrap vs upgrade. No ad-hoc `systemctl` edits or hand-built `scp`.
 
+**NEVER pass `--upgrade` (or `--skip-pull`) to `setup-broker-host.sh`.** They are back-compat **no-ops** — the script is idempotent and auto-detects bootstrap vs upgrade; there is no "upgrade mode" to opt into. Invoke it **plain** (`bash scripts/setup-broker-host.sh`, optionally with `--test`/`--yes`/`--clean`), or pass **`--ref main`** when you also want it to fetch + checkout + redeploy `main`. Do not add an `--upgrade` flag to any new script, runbook, doc, or CLI guidance; if you find an existing `--upgrade` reference in an active (non-archived) operator path, replace it with `--ref main` (deploy) or plain (ensure) in the same change.
+
 ### SSH access to the remote broker host
 On the operator machine, **SSH into the prod broker with the zsh alias `ssh-agentkeys`** (= `bash $AGENTKEYS_REPO/scripts/ssh-broker.sh prod`, which uses EC2 Instance Connect under AWS profile `agentkeys-broker`). Use it for read-only diagnostics (worker logs, env, status) — it is the sanctioned remote-shell entry point; do not hand-roll `aws ec2-instance-connect ssh` or raw `ssh`. Pass a trailing command to run non-interactively: `ssh-agentkeys 'systemctl status agentkeys-worker-memory'`. The login user is `agentkey` (uid 1001); it is in the `sudo` group but sudo **requires a password and a TTY**, so `journalctl`/reading `/etc/agentkeys/*.env` (owned `agentkeys:agentkeys 0600`) need an interactive session — non-interactive `ssh-agentkeys '<cmd>'` can only run unprivileged commands. For privileged log reads, open an interactive `ssh-agentkeys` shell and run `sudo` there. (`ssh-broker.sh test` / `--fallback` reach the test stack / use the `.pem` when EC2-IC is down.)
 
diff --git a/docs/ci-setup.md b/docs/ci-setup.md
index 0e270bc4..ed8bd943 100644
--- a/docs/ci-setup.md
+++ b/docs/ci-setup.md
@@ -477,7 +477,7 @@ The IAM role can stay provisioned indefinitely — without the secret it can't b
 
 Per [issue #101](https://github.com/litentry/agentKeys/issues/101) "Out of scope":
 
-- **Prod broker auto-deploy** — never. The prod broker EC2 stays manual via `bash scripts/setup-broker-host.sh --upgrade` from the operator laptop, per CLAUDE.md "Remote broker host (single entry point)".
+- **Prod broker auto-deploy** — never. The prod broker EC2 stays manual via `bash scripts/setup-broker-host.sh --ref main` from the operator laptop, per CLAUDE.md "Remote broker host (single entry point)".
 - **Auto-deploy of test Heima EVM contracts** — deferred to a follow-up PR (issue #101 rollout plan step 7). Contract redeploys mint new addresses and require the `SECRETS_REWRITE_PAT` token to update six `TEST_*_ADDRESS_HEIMA` secrets — more risk than the broker deploy, so it ships separately.
 - **Mainnet prod contract redeploy** — never automatic. Manual via `bash scripts/setup-heima.sh` only.
 
diff --git a/scripts/setup-cloud.sh b/scripts/setup-cloud.sh
index 04fd2777..7003a72b 100755
--- a/scripts/setup-cloud.sh
+++ b/scripts/setup-cloud.sh
@@ -760,7 +760,7 @@ ensure_ssm_managed() {
   done
   die "SSM: $INSTANCE_ID never reached PingStatus=Online (last: ${ping:-none}) after ~3min. The role now carries AmazonSSMManagedInstanceCore, so the on-host amazon-ssm-agent likely isn't running. (Re)start it via the single entry point, then re-run this step:
      bash scripts/ssh-broker.sh $([ "$TEST_MODE" = "1" ] && echo test || echo prod)
-     sudo bash /opt/agentkeys-src/scripts/setup-broker-host.sh --upgrade   # installs+enables the agent
+     sudo bash /opt/agentkeys-src/scripts/setup-broker-host.sh --ref main   # idempotent; installs+enables the agent
    or reboot (broker auto-restarts via systemd): aws --region $REGION ec2 reboot-instances --instance-ids $INSTANCE_ID"
 }
 

From a5abb939782e2b6e41630a209b40a6a6f8e26e4b Mon Sep 17 00:00:00 2001
From: Hanwen Cheng <heawen.cheng@gmail.com>
Date: Sun, 31 May 2026 18:29:39 +0800
Subject: [PATCH 07/23] fix(setup-cloud): default HOME in the step-15 SSM
 remote script (set -u unbound-var)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

SSM RunShellScript executes the step-15 mcp-bring-up script as root with a
MINIMAL env (no HOME). Under set -euo pipefail the first $HOME use
(export PATH=$HOME/.cargo/bin) aborted with 'HOME: unbound variable' — a latent
bug that only surfaced once SSM delivery started working (previously it failed at
send-command). Default HOME to /root before any $HOME use. Also document
--only-step 15 in the script's re-run examples.
---
 scripts/setup-cloud.sh | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/scripts/setup-cloud.sh b/scripts/setup-cloud.sh
index 7003a72b..7c98d194 100755
--- a/scripts/setup-cloud.sh
+++ b/scripts/setup-cloud.sh
@@ -793,6 +793,10 @@ do_step_15() {
   mcp_bring_up_script=$(cat <<EOSH
 #!/usr/bin/env bash
 set -euo pipefail
+# SSM RunShellScript runs this as root with a MINIMAL env (no HOME). Under set -u
+# an unset \$HOME is a fatal "unbound variable", which broke step 15 the moment
+# SSM delivery started working. Default it before any \$HOME use (root => /root).
+export HOME="\${HOME:-/root}"
 export PATH="\$HOME/.cargo/bin:\$PATH"
 
 if ! command -v cargo >/dev/null 2>&1; then
@@ -901,6 +905,7 @@ do_step_16() {
   printf "    bash scripts/setup-cloud.sh --only-step 6   # re-UPSERT DNS\n" >&2
   printf "    bash scripts/setup-cloud.sh --only-step 12  # re-create SSH user (e.g. after EC2 replace)\n" >&2
   printf "    bash scripts/setup-cloud.sh --only-step 13  # re-run per-data-class provisioning\n" >&2
+  printf "    bash scripts/setup-cloud.sh --only-step 15  # re-run the MCP bring-up on the broker via SSM (add --test for the test broker)\n" >&2
   printf "    bash scripts/setup-cloud.sh --only-step 15  # re-deploy agentkeys-mcp-server on broker (cargo install --git)\n" >&2
   printf "    bash scripts/setup-cloud.sh --only-step 15 --test  # same for test-mcp.\${ZONE}\n\n" >&2
 }

From 91442cc3d8a83410cd194649f355515b2430259a Mon Sep 17 00:00:00 2001
From: Hanwen Cheng <heawen.cheng@gmail.com>
Date: Sun, 31 May 2026 18:35:14 +0800
Subject: [PATCH 08/23] docs(CLAUDE): generalize the never---upgrade rule to
 any idempotent setup script

Broaden the rule from setup-broker-host.sh to all idempotent setup scripts
(setup-cloud.sh, setup-heima.sh, heima-* helpers) and restore the actionable
guidance (invoke plain / --only-step N, or --ref main for a broker redeploy;
replace existing active-path --upgrade references).
---
 CLAUDE.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 3d99fae8..408c7183 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -90,7 +90,7 @@ Also: never gloss over a partial implementation in a demo doc or runbook. If the
 ## Remote broker host (single entry point)
 All remote-host changes (binary upgrades, systemd edits, nginx/certbot, env tweaks, mock-server redeploys) MUST go through `bash scripts/setup-broker-host.sh` — it's idempotent and auto-detects bootstrap vs upgrade. No ad-hoc `systemctl` edits or hand-built `scp`.
 
-**NEVER pass `--upgrade` (or `--skip-pull`) to `setup-broker-host.sh`.** They are back-compat **no-ops** — the script is idempotent and auto-detects bootstrap vs upgrade; there is no "upgrade mode" to opt into. Invoke it **plain** (`bash scripts/setup-broker-host.sh`, optionally with `--test`/`--yes`/`--clean`), or pass **`--ref main`** when you also want it to fetch + checkout + redeploy `main`. Do not add an `--upgrade` flag to any new script, runbook, doc, or CLI guidance; if you find an existing `--upgrade` reference in an active (non-archived) operator path, replace it with `--ref main` (deploy) or plain (ensure) in the same change.
+**NEVER pass `--upgrade` (or `--skip-pull`) to any idempotent setup script** (`setup-broker-host.sh`, `setup-cloud.sh`, the `heima-*` / `setup-heima.sh` helpers, etc.). They are back-compat **no-ops** — these scripts are idempotent and auto-detect bootstrap vs upgrade; there is no "upgrade mode" to opt into. Invoke them **plain** (optionally with `--test` / `--yes` / `--clean` / `--only-step N`), or pass **`--ref main`** to `setup-broker-host.sh` when you also want it to fetch + checkout + redeploy `main`. Do not add an `--upgrade` flag to any new script, runbook, doc, or CLI guidance; if you find an existing `--upgrade` reference in an active (non-archived) operator path, replace it with the idempotent invocation (`--ref main` for deploy, plain for ensure) in the same change.
 
 ### SSH access to the remote broker host
 On the operator machine, **SSH into the prod broker with the zsh alias `ssh-agentkeys`** (= `bash $AGENTKEYS_REPO/scripts/ssh-broker.sh prod`, which uses EC2 Instance Connect under AWS profile `agentkeys-broker`). Use it for read-only diagnostics (worker logs, env, status) — it is the sanctioned remote-shell entry point; do not hand-roll `aws ec2-instance-connect ssh` or raw `ssh`. Pass a trailing command to run non-interactively: `ssh-agentkeys 'systemctl status agentkeys-worker-memory'`. The login user is `agentkey` (uid 1001); it is in the `sudo` group but sudo **requires a password and a TTY**, so `journalctl`/reading `/etc/agentkeys/*.env` (owned `agentkeys:agentkeys 0600`) need an interactive session — non-interactive `ssh-agentkeys '<cmd>'` can only run unprivileged commands. For privileged log reads, open an interactive `ssh-agentkeys` shell and run `sudo` there. (`ssh-broker.sh test` / `--fallback` reach the test stack / use the `.pem` when EC2-IC is down.)

From 3eb6f51089376e6c8a799840e943399e3ed2c567 Mon Sep 17 00:00:00 2001
From: Hanwen Cheng <heawen.cheng@gmail.com>
Date: Sun, 31 May 2026 18:45:23 +0800
Subject: [PATCH 09/23] fix(setup-cloud): step-15 poll heartbeat + 25-min cap
 (cold cargo build is not a hang)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

setup-mcp-host.sh runs 'cargo install --git' to build agentkeys-mcp-server FROM
SOURCE; a cold build on the t3.medium broker takes 10-20 min, but step 15 polled
SILENTLY with a 10-min cap — so it looked hung and timed out mid-build. Add a
~30s heartbeat (status + elapsed) and raise the cap to 25 min. On timeout, state
the build is likely still running on the broker (not a failure) and point to
--from-step 15 to resume (cargo cache => fast) plus the get-command-invocation
watch command.
---
 scripts/setup-cloud.sh | 30 ++++++++++++++++++++++--------
 1 file changed, 22 insertions(+), 8 deletions(-)

diff --git a/scripts/setup-cloud.sh b/scripts/setup-cloud.sh
index 7c98d194..fe42c4f7 100755
--- a/scripts/setup-cloud.sh
+++ b/scripts/setup-cloud.sh
@@ -837,12 +837,17 @@ EOSH
     die "aws ssm send-command failed — does $INSTANCE_ID have amazon-ssm-agent + the SSM instance profile? Detail: $_err"
   fi
   rm -f "$_send_err"
-  ok "SSM command $cmd_id queued on $INSTANCE_ID; polling for completion (max 10 min)"
-
-  # Poll every 10s for up to 10 min. setup-mcp-host.sh is normally <3 min;
-  # first-time runs with cargo install may take longer.
-  local status="Pending"
-  for i in $(seq 1 60); do
+  ok "SSM command $cmd_id queued on $INSTANCE_ID; polling for completion (up to 25 min)"
+
+  # Poll every 10s for up to 25 min. setup-mcp-host.sh runs `cargo install --git`
+  # to build agentkeys-mcp-server FROM SOURCE; a COLD build on a t3.medium can
+  # take 10–20 min. The old 10-min cap timed out mid-build, and the silent poll
+  # (no per-iteration output) looked like a hang. Heartbeat ~every 30s so it's
+  # visibly alive, and on a genuine timeout the build is usually still running on
+  # the broker (not a failure) — re-running --from-step 15 resumes polling and
+  # the cargo cache makes that build finish fast.
+  local status="Pending" last=""
+  for i in $(seq 1 150); do
     sleep 10
     status=$(aws ssm get-command-invocation \
       --region "$REGION" \
@@ -864,10 +869,19 @@ EOSH
           --region "$REGION" --command-id "$cmd_id" --instance-id "$INSTANCE_ID" \
           --query "StandardErrorContent" --output text 2>/dev/null \
           | tail -50 | sed 's/^/      /' >&2 || true
-        die "MCP bring-up failed; see SSM command $cmd_id in CloudWatch" ;;
+        die "MCP bring-up failed; inspect: aws ssm get-command-invocation --region $REGION --command-id $cmd_id --instance-id $INSTANCE_ID --query StandardErrorContent --output text" ;;
     esac
+    # Heartbeat on the first tick, on any status change, and ~every 30s, so a long
+    # cold cargo build is visibly alive rather than looking hung.
+    if [ "$status" != "$last" ] || [ $(( i % 3 )) -eq 1 ]; then
+      printf "    … MCP bring-up running: status=%s, ~%ds elapsed (cold cargo build ~10–20 min)\n" "$status" "$(( i * 10 ))" >&2
+      last="$status"
+    fi
   done
-  die "MCP bring-up timed out after 10 min (status=$status); check SSM command $cmd_id"
+  die "MCP bring-up still '$status' after 25 min — the cargo build is most likely STILL RUNNING on the broker (not a failure). Re-run to resume polling (idempotent; the cargo cache makes the build finish fast):
+     bash scripts/setup-cloud.sh --from-step 15$([ "$TEST_MODE" = "1" ] && echo " --test" || echo "")
+   Or watch it directly:
+     aws ssm get-command-invocation --region $REGION --command-id $cmd_id --instance-id $INSTANCE_ID --query Status --output text"
 }
 
 do_step_16() {

From 4bd39eb38bb1befc55f735ad91f17707af3ab6ba Mon Sep 17 00:00:00 2001
From: Hanwen Cheng <heawen.cheng@gmail.com>
Date: Sun, 31 May 2026 19:24:52 +0800
Subject: [PATCH 10/23] perf(setup-mcp-host): build agentkeys-mcp-server via
 cached in-repo cargo build, not cargo install --git
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Step 15 took ~10 min because setup-mcp-host.sh used 'cargo install --git --force':
it re-clones the repo and builds agentkeys-mcp-server + its WHOLE dep tree
(aws-sdk-s3, tokio, k256, reqwest, ...) in a THROWAWAY target every run — a cold
release build on the 2-vCPU t3.medium broker. setup-broker-host.sh already
compiled those same deps into $REPO_ROOT/target/release (persistent, incremental),
and the harness builds the MCP server with persistent cargo caches too; the
cargo-install path was the lone build throwing the cache away.

Build it the same way the broker/workers (and harness) do: cd $REPO_ROOT
(/opt/agentkeys-src, already checked out by step 15's clone/reset) and
'cargo build --release --locked -p agentkeys-mcp-server', install from
target/release. Reuses the shared dep cache => incremental (seconds-2 min), not a
10-20 min cold build. Worst case (no prior build) is no slower than before, and
all re-runs are fast since target/ persists.
---
 scripts/setup-mcp-host.sh | 38 ++++++++++++++++++--------------------
 1 file changed, 18 insertions(+), 20 deletions(-)

diff --git a/scripts/setup-mcp-host.sh b/scripts/setup-mcp-host.sh
index 37fdd64b..63d86072 100755
--- a/scripts/setup-mcp-host.sh
+++ b/scripts/setup-mcp-host.sh
@@ -186,7 +186,7 @@ echo "    install dir:       ${INSTALL_DIR}" >&2
 echo "    run user:          ${RUN_USER}" >&2
 echo "    env file:          ${ENV_FILE}" >&2
 echo "    mcp binary dst:    ${MCP_BIN_DST}" >&2
-echo "    mcp install:       cargo install --git ${AGENTKEYS_REPO_URL:-https://github.com/litentry/agentKeys.git} --branch ${AGENTKEYS_REV:-main}" >&2
+echo "    mcp build:         cargo build --release -p agentkeys-mcp-server  (in ${REPO_ROOT}, cached/incremental)" >&2
 echo "    with nginx:        ${WITH_NGINX}" >&2
 echo "    with certbot:      ${WITH_CERTBOT}" >&2
 echo "    with build:        ${WITH_BUILD}" >&2
@@ -332,31 +332,29 @@ fi  # MODE == self-hosted (closes step 3 self-hosted branch)
 # Override repo/rev for development (e.g. testing a PR branch):
 #   AGENTKEYS_REPO_URL=https://github.com/me/agentKeys.git \
 #   AGENTKEYS_REV=my-pr-branch bash scripts/setup-mcp-host.sh
-head "4/9 install agentkeys-mcp-server (cargo install --git)"
-REPO_URL="${AGENTKEYS_REPO_URL:-https://github.com/litentry/agentKeys.git}"
-REV="${AGENTKEYS_REV:-main}"
-INSTALL_CACHE="${HOME}/.cache/agentkeys-mcp-install"
+head "4/9 build agentkeys-mcp-server (cached workspace build)"
 
 if [ "$WITH_BUILD" = "yes" ]; then
   command -v cargo >/dev/null 2>&1 \
-    || fail "cargo not found — install Rust toolchain (curl https://sh.rustup.rs | sh) or pass --without-build if binary already at $MCP_BIN_DST"
-  mkdir -p "$INSTALL_CACHE"
-  ok "cargo install --git $REPO_URL --branch $REV → $INSTALL_CACHE/bin/"
-  # --force: cargo install won't overwrite "the same version" without it.
-  # With --git there's no semver to compare against, so --force is the
-  # right call. cargo's incremental compile + on-disk cache keep re-runs
-  # fast (~5s when nothing changed; ~2 min on a fresh build).
-  cargo install --quiet --force \
-    --git "$REPO_URL" --branch "$REV" \
-    --bin agentkeys-mcp-server \
-    --root "$INSTALL_CACHE" \
-    agentkeys-mcp-server \
-    || fail "cargo install --git $REPO_URL@$REV failed"
+    || fail "cargo not found — install Rust (curl https://sh.rustup.rs | sh) or pass --without-build if the binary is already at $MCP_BIN_DST"
+  # Build IN the on-host repo checkout ($REPO_ROOT, e.g. /opt/agentkeys-src) using
+  # its PERSISTENT target/ — NOT `cargo install --git`, which re-clones + builds
+  # the ENTIRE dep tree in a throwaway target every run (a ~10–20 min COLD build
+  # on the t3.medium broker). setup-broker-host.sh already compiled
+  # aws-sdk/tokio/k256/etc. into this same target/release, and the target persists
+  # across re-runs, so `cargo build -p` is INCREMENTAL — only the mcp-server crate
+  # recompiles (seconds–2 min). Same cached-build approach as setup-broker-host.sh
+  # and harness/phase1-wire-demo.sh. ($REPO_ROOT was already checked out to the
+  # desired ref by the caller — e.g. setup-cloud.sh step 15's clone/reset — so no
+  # separate `--git` fetch is needed; we build the code that's actually here.)
+  ok "cargo build --release -p agentkeys-mcp-server (in $REPO_ROOT, reusing the target/release cache)"
+  ( cd "$REPO_ROOT" && cargo build --release --locked -p agentkeys-mcp-server ) \
+    || fail "cargo build -p agentkeys-mcp-server failed in $REPO_ROOT"
 fi
 
-CACHED_BIN="$INSTALL_CACHE/bin/agentkeys-mcp-server"
+CACHED_BIN="$REPO_ROOT/target/release/agentkeys-mcp-server"
 if [ ! -x "$CACHED_BIN" ]; then
-  fail "$CACHED_BIN not installed; drop --without-build or place the binary at $MCP_BIN_DST yourself"
+  fail "$CACHED_BIN not built; drop --without-build or place the binary at $MCP_BIN_DST yourself"
 fi
 
 src_sha=$(sha256sum "$CACHED_BIN" | awk '{print $1}')

From 74a9e309ff2e35f6c638a86e820394285a35e3d9 Mon Sep 17 00:00:00 2001
From: Hanwen Cheng <heawen.cheng@gmail.com>
Date: Sun, 31 May 2026 21:53:24 +0800
Subject: [PATCH 11/23] build+scripts: cache sandbox MCP build, move hosted MCP
 off cloud setup, drop operator flags

- harness/phase1-wire-demo.sh: cross-build target -> named docker volume (off the macOS bind-mount); copy only the 3 binaries out to the host path the upload step reads.

- setup-cloud.sh: step 15 (hosted MCP on broker) is now a no-op redirect. It is a broker-host concern + the deferred Hosted-LLM path (#152), not cloud/IAM.

- setup-broker-host.sh / setup-mcp-host.sh: state-driven idempotency over operator flags. Drop --without-workers / --without-build / --clean / --no-clean; unattended by default (--yes/--non-interactive kept as accepted no-ops for CI). Hosted MCP auto-converges when its binary is already installed.

- docs/operator-runbook-wire.md: wrap-up section -- three setup entry points (run only what changed), no-flag idempotent posture, right test order; build-cache + troubleshooting updates.

- docs/spec/plans/issue-107-mcp-demo-runbook.md: correct the B.5 deploy path (setup-mcp-host.sh, no --with-mcp).

Refs #149, #152.
---
 docs/operator-runbook-wire.md                 |  24 ++-
 docs/spec/plans/issue-107-mcp-demo-runbook.md |  20 +--
 harness/phase1-wire-demo.sh                   |  33 +++-
 scripts/setup-broker-host.sh                  |  62 ++++----
 scripts/setup-cloud.sh                        | 141 +++---------------
 scripts/setup-mcp-host.sh                     |  43 +++---
 6 files changed, 128 insertions(+), 195 deletions(-)

diff --git a/docs/operator-runbook-wire.md b/docs/operator-runbook-wire.md
index 383e53c2..bec0f6eb 100644
--- a/docs/operator-runbook-wire.md
+++ b/docs/operator-runbook-wire.md
@@ -99,6 +99,23 @@ Note it puts the agent key back on the master; use only for quick loops.
 | **Proves** | the wire + hook + memory-injection **plumbing** works | the same, against **real IAM infra** (real signing + isolation) |
 | **Cost / risk** | free, can't break anything | real gas/cost, mutates real account state |
 
+## Setup entry points — run only what changed (idempotent, no flags to remember)
+
+`--light` needs none of this (it's self-contained). For `--real`, the live infra is owned by **three idempotent scripts — run only the one whose domain changed**, then re-run the harness:
+
+| Script | Owns | Re-run when |
+|---|---|---|
+| [`scripts/setup-cloud.sh`](../scripts/setup-cloud.sh) | **Cloud / IAM only** (as `agentkeys-admin`) — SES, S3, DNS, roles, OIDC | a permission / role / DNS change |
+| [`scripts/setup-broker-host.sh`](../scripts/setup-broker-host.sh) | **The broker host** — broker + signer + 4 workers (binaries, systemd, nginx) | broker/worker code changed |
+| [`scripts/setup-heima.sh`](../scripts/setup-heima.sh) | **The chain** — contracts + per-actor binding ceremonies | a chain / contract change |
+
+All three are **idempotent and unattended by default** — a re-run with the same inputs converges and exits 0 without re-applying. There are **no opt-in/opt-out flags to remember**: behaviour follows state (workers always build but skip when up-to-date; the broker self-heals a bad feature build on its own). `--yes` / `--non-interactive` are still *accepted* (CI passes them) but are no longer needed.
+
+**The wire demo does NOT need a broker-hosted MCP server** — its MCP server runs **in the sandbox** (cross-built there once, then cached; see Prerequisites). The broker-hosted MCP endpoint is the *Hosted-LLM* path (xiaozhi / vendor-cloud), **deferred to [#152](https://github.com/litentry/agentKeys/issues/152)**; `setup-cloud.sh` step 15 is now a no-op that points there. So the right order to test the wire flow is just:
+
+1. *(only if the matching infra above changed)* run that one script
+2. `bash harness/phase1-wire-demo.sh --real --webauthn`
+
 ## Prerequisites
 
 **Always:** Rust toolchain (`rustup default stable`) + `jq` (`brew install jq`).
@@ -109,7 +126,7 @@ Note it puts the agent key back on the master; use only for quick loops.
   docker run --security-opt seccomp=unconfined -d -p 8080:8080 ghcr.io/agent-infra/sandbox:latest
   ```
   The `--security-opt seccomp=unconfined` flag is required (Docker's default seccomp blocks syscalls the sandbox needs; without it the container exits silently). Re-run after every Docker Desktop upgrade.
-- A **reachable rust image** for the aarch64-linux cross-build (the sandbox is aarch64 Linux; the harness cross-builds the agent binary in an `arm64` rust container). The **first** build is slow; after that re-runs are **incremental** — the harness persists cargo's registry + compiled artifacts in docker volumes and bakes the OpenSSL build deps into a cached `agentkeys-sandbox-builder` image, recompiling only when a tracked source file changed (and restarting the sandbox MCP server when the binary changed). If Docker Hub is unreachable, pre-pull or point at a mirror: `RUST_BUILD_IMAGE=<local-or-mirror-rust-image>`.
+- A **reachable rust image** for the aarch64-linux cross-build (the sandbox is aarch64 Linux; the harness cross-builds the agent binary in an `arm64` rust container). The **first** build is slow; after that re-runs are **incremental** — the harness persists cargo's registry, git db, the rustup toolchain, **and the `target/` dir** in named docker volumes, and bakes the OpenSSL build deps into a cached `agentkeys-sandbox-builder` image, recompiling only when a tracked source file changed (and restarting the sandbox MCP server when the binary changed). The `target/` dir lives in a **named volume** (`agentkeys-sandbox-target`), *not* a host bind-mount — on macOS a bind-mounted target routes cargo's thousands of small incremental files through the Docker VM's virtiofs layer and dominates re-run time; only the three final binaries are copied out to `target/sandbox-linux/release/`. If Docker Hub is unreachable, pre-pull or point at a mirror: `RUST_BUILD_IMAGE=<local-or-mirror-rust-image>`.
 - **Hermes** in the sandbox — the harness installs it (guarded `curl|bash`) if absent; needs GitHub reachable.
 
 **Real mode only:**
@@ -217,9 +234,9 @@ Re-running `agentkeys wire hermes` is always safe — unchanged scripts/config s
 | cap-mint → 401/`OperatorMismatch` (`session_omni != operator_omni`) | the session is for a *different* operator (e.g. the legacy `alice` email session, omni `4231cd8f…` ≠ agent operator `941cb1c3…`) | `0.7` now detects the omni mismatch and re-mints from `OPERATOR_KEY_FILE`. If `0.7` fails with "wrong operator", point `OPERATOR_KEY_FILE` at the master key whose broker omni == `operator_omni` |
 | memory put/get → HTTP **502** `{"reason":"s3_put"}` / `{"reason":"s3_get"}` | the MCP `http` backend didn't forward per-actor STS creds, so the worker fell back to its EC2 instance profile (SES-only, **no S3**) → AccessDenied on every op. cap-mint + chain-verify themselves SUCCEED (the agent IS authorized); the gap was the credential **relay**. | **Fixed (issue #90):** the backend now mints agent-tagged STS creds (`0.8` agent session → broker `/v1/mint-oidc-jwt` → `AssumeRoleWithWebIdentity(memory-role)`, tagged `agentkeys_actor_omni`) and forwards them as `X-Aws-*` headers, so AWS scopes S3 to `bots/<actor>/memory/`. If it still 502s: confirm `P.1 install` shows "agent redeemed in-sandbox" (or `0.8 agent session` under `--reuse-agent`) and `P.3 grant` granted the scope; the relay needs the in-sandbox agent session + `MEMORY_ROLE_ARN`/`VAULT_ROLE_ARN`/`REGION` from `operator-workstation.env`. Optional strict enforcement: set `AGENTKEYS_WORKER_REQUIRE_STS=1` in the worker env (rejects credless requests with 401 instead of falling back). |
 | **Phase P** `P.0`/`P.1`/`P.2`/`P.3` fails | `P.0` create: broker `/v1/agent/create` down or the operator session (0.7) invalid. `P.1` install: stale sandbox `agentkeys-daemon` (no `--init-link-code`), broker `/v1/auth/link-code/redeem` down, or an expired link code (>600s). `P.2` bind: on-chain `registerAgentDevice` failed (master gas / RPC). `P.3` grant: `heima-scope-set --webauthn` needs K11 webauthn enrollment + Touch ID. | `P.0` check 0.7 + the broker. `P.1` 1.3 rebuilds+uploads the daemon binary — just re-run (the agent reuses its K10, so a retry is safe). `P.2` check the master wallet balance / RPC. `P.3` enroll K11 webauthn + pass `--webauthn`. For a quick loop without pairing use `--reuse-agent`. |
-| `1.3 linux build` is slow even for a one-line change | rustup re-downloaded the host-pinned toolchain (~250 MB, ~4 min) because `/usr/local/rustup` wasn't cached | fixed: the toolchain now persists in the `RUSTUP_VOL` docker volume — the **first** build seeds it (~4 min), later builds skip the download (incremental compile only, ~15 s) |
+| `1.3 linux build` is slow even for a one-line change | (a) rustup re-downloaded the host-pinned toolchain (~250 MB, ~4 min) because `/usr/local/rustup` wasn't cached; (b) on macOS, cargo's `target/` sat on a **host bind-mount**, so every incremental file crossed the Docker VM's virtiofs layer | fixed on both: (a) the toolchain persists in `RUSTUP_VOL`; (b) `CARGO_TARGET_DIR` is now a **named volume** (`agentkeys-sandbox-target`) on the VM's native fs, with only the 3 final binaries copied out. First build seeds the caches (~4 min); later builds are incremental compile only (~15 s) |
 | Phase 1 `1.3 linux build` → "cannot pull" | Docker Hub unreachable for the base image | `RUST_BUILD_IMAGE=<local/mirror rust image>` or pre-pull `rust:1.83-slim-bookworm` |
-| `1.3 linux build` won't pick up a Rust edit | gate compares source mtime vs binary; re-runs rebuild automatically on a real edit | to force a from-scratch rebuild: `rm -rf target/sandbox-linux && docker volume rm agentkeys-sandbox-cargo-registry agentkeys-sandbox-cargo-git`; to rebuild the deps image: `docker rmi agentkeys-sandbox-builder:1.83-bookworm` |
+| `1.3 linux build` won't pick up a Rust edit | gate compares source mtime vs binary; re-runs rebuild automatically on a real edit | to force a from-scratch rebuild: `rm -rf target/sandbox-linux && docker volume rm agentkeys-sandbox-target agentkeys-sandbox-cargo-registry agentkeys-sandbox-cargo-git` (the `target/` dir now lives in the `agentkeys-sandbox-target` volume — `target/sandbox-linux` on the host holds only the 3 extracted binaries); to rebuild the deps image: `docker rmi agentkeys-sandbox-builder:1.83-bookworm` |
 | `wire` step 0 → `fail hermes not installed` | Hermes not on the sandbox PATH | the harness installs it; or run the guarded install (Appendix) — needs GitHub reachable |
 | `wire` step 3 → `fail … already has a top-level hooks:` | hand-authored `hooks:` in `~/.hermes/config.yaml` | merge manually or remove it, then re-run |
 | `hook check` blocks with `agentkeys_unreachable` | MCP server down | start it (the harness does in Phase 1); check `AGENTKEYS_MCP_URL` |
@@ -296,3 +313,4 @@ echo '{"tool_name":"x"}'                  | agentkeys hook audit
 - [`docs/spec/plans/phase1-wire-harness-test-plan.md`](spec/plans/phase1-wire-harness-test-plan.md) — the action table + automation decisions
 - [`docs/agent-iam-strategy.md`](agent-iam-strategy.md) §3.6/§3.7/§4.3 · [`docs/arch.md`](arch.md) §22d · [`docs/wiki/agent-iam-guarantee-glossary.md`](wiki/agent-iam-guarantee-glossary.md)
 - [Issue #133](https://github.com/litentry/agentKeys/issues/133) — multi-runtime hook reference configs (Phase 1.b)
+- [Issue #152](https://github.com/litentry/agentKeys/issues/152) — **scope:** this runbook covers the **Local-LLM / Task-agent** path only (stdio MCP server built + run *in the sandbox*). The **Hosted-LLM** path (xiaozhi / vendor-cloud — a broker-hosted `mcp-endpoint` the remote LLM connects *into*, per arch.md §22c.2 / §22d.3) is deferred to #152.
diff --git a/docs/spec/plans/issue-107-mcp-demo-runbook.md b/docs/spec/plans/issue-107-mcp-demo-runbook.md
index 6736fe85..25843bca 100644
--- a/docs/spec/plans/issue-107-mcp-demo-runbook.md
+++ b/docs/spec/plans/issue-107-mcp-demo-runbook.md
@@ -421,23 +421,17 @@ Capture for the next step:
 - A real actor omni from `heima-agent-register.sh` (32-byte hex).
 - A device key hash from `heima-device-register.sh` (32-byte hex).
 
-### B.5 Deploy the MCP server on the broker
+### B.5 Deploy the MCP server on the broker (hosted-LLM path — issue #152, deferred)
 
-**Production / test (one command from the operator workstation):** [`scripts/setup-cloud.sh`](../../../scripts/setup-cloud.sh) step 15 SSMs the broker EC2 and runs [`scripts/setup-mcp-host.sh`](../../../scripts/setup-mcp-host.sh) there. Same step handles prod (`mcp.${ZONE}`) and test (`test-mcp.${ZONE}`).
+> **Moved.** The broker-hosted MCP endpoint is the **Hosted-LLM** path (a remote vendor LLM connects *inward* over WSS) — tracked in [#152](https://github.com/litentry/agentKeys/issues/152) and **deferred**. It is a broker-host concern, so it no longer lives in `setup-cloud.sh` (which is IAM/permission-only). The old `setup-cloud.sh --only-step 15` SSM-ran `setup-mcp-host.sh`, cloning `main` and cold-building via `cargo install --git` (~10–20 min EVERY run). Enable it on the broker with [`setup-mcp-host.sh`](../../../scripts/setup-mcp-host.sh) (cached incremental `cargo build -p` against the checkout); thereafter `setup-broker-host.sh` re-converges it automatically — **no flag to remember**:
 
 ```bash
-# Bring up prod MCP on the broker (cargo installs from github.com/litentry/agentKeys main)
-bash scripts/setup-cloud.sh --env-file scripts/operator-workstation.env --only-step 15
-
-# Bring up test MCP on the same broker (test-mcp.litentry.org)
-bash scripts/setup-cloud.sh --env-file scripts/operator-workstation.test.env --test --only-step 15
-
-# Pin to a PR branch / fork while developing
-AGENTKEYS_REPO_URL=https://github.com/me/agentKeys.git AGENTKEYS_REV=my-feature-branch \
-  bash scripts/setup-cloud.sh --only-step 15
+# On the broker (reach it via scripts/ssh-broker.sh), from the /opt/agentkeys-src checkout:
+sudo bash /opt/agentkeys-src/scripts/setup-mcp-host.sh            # prod  → mcp.${ZONE}
+sudo bash /opt/agentkeys-src/scripts/setup-mcp-host.sh --test     # test → test-mcp.${ZONE}
 ```
 
-The step polls the SSM command for up to 10 min and tails the last 30 lines of stdout when it completes (or stderr on failure). Idempotent — re-runs short-circuit when state is already correct.
+Once the MCP binary is installed, every `setup-broker-host.sh` run keeps it converged (idempotent), so routine broker setups need nothing extra. **The Local-LLM / Task-agent wire demo does NOT need this** — that MCP server runs in the agent's own sandbox (see [`docs/operator-runbook-wire.md`](../../operator-runbook-wire.md) + `harness/phase1-wire-demo.sh`).
 
 **Local development install (laptop / Claude Code / Codex CLI / Claude Desktop):**
 
@@ -664,7 +658,7 @@ sudo systemctl disable --now agentkeys-mcp-server mcp-endpoint-server
 - Parent-control UI (#111) — until it lands, simulate Act 3's revoke via a curl call through the relay between the two voice prompts.
 - Live broker `/v1/revoke/cap/:id` lands in M4 — until then, `cap.revoke` is the structured stub on the MCP server.
 - Vendor token mint is hand-edited into `MCP_VENDOR_TOKENS` for the HTTP transport. The mcp-endpoint transport bypasses vendor tokens (the relay URL token is the binding) so this isn't on the critical path for B.
-- `scripts/setup-broker-host.sh --with-mcp-endpoint` — fold both systemd units (relay + MCP server) into the existing idempotent host setup. Follow-up.
+- The MCP-server systemd unit is already re-converged by `setup-broker-host.sh` once installed (state-driven, no flag — #152). Follow-up: bring the `mcp-endpoint` relay unit under the same auto-convergence so both come up from state with nothing to pass.
 ---
 
 ## Where to file demo-specific bugs
diff --git a/harness/phase1-wire-demo.sh b/harness/phase1-wire-demo.sh
index 6d7140f1..947e177c 100755
--- a/harness/phase1-wire-demo.sh
+++ b/harness/phase1-wire-demo.sh
@@ -722,8 +722,17 @@ phase1_sandbox() {
 # OS — so the agent binary must be cross-built.
 #
 # Caching (so re-runs are fast + idempotent, like a local `cargo build`):
-#   • TARGET dir        → target/sandbox-linux is bind-mounted to the host, so
-#                         compiled crates + deps persist across runs.
+#   • TARGET dir        → CARGO_TARGET_DIR is a NAMED docker volume, NOT a host
+#                         bind-mount. cargo's incremental build churns thousands
+#                         of small files in target/; on macOS a host bind-mount
+#                         routes every stat/read/write through the Docker VM's
+#                         virtiofs/gRPC-FUSE layer, which dominates wall-clock on
+#                         re-runs. A named volume keeps that I/O on the VM's native
+#                         fs (the single biggest re-run speedup). After a success,
+#                         ONLY the three final binaries are copied OUT to the host
+#                         target/sandbox-linux/release/ (3 sequential writes —
+#                         cheap over a bind-mount) for the idempotency gate +
+#                         upload step to read.
 #   • REGISTRY + git    → named docker volumes, so the crates.io index and the
 #                         downloaded .crate sources survive the --rm container
 #                         (no multi-minute re-fetch every run).
@@ -750,6 +759,10 @@ CARGO_GIT_VOL="${CARGO_GIT_VOL:-agentkeys-sandbox-cargo-git}"
 # seeded from the image's /usr/local/rustup on first use, then caches the
 # downloaded pinned toolchain so later runs only recompile the changed crate.
 RUSTUP_VOL="${RUSTUP_VOL:-agentkeys-sandbox-rustup}"
+# Named volume for cargo's target dir — see the TARGET dir note above. Holding
+# the incremental build off the macOS host bind-mount is the single biggest
+# re-run speedup; only the final binaries are extracted to $LINUX_TARGET_DIR.
+CARGO_TARGET_VOL="${CARGO_TARGET_VOL:-agentkeys-sandbox-target}"
 
 # True (0) when any tracked source is newer than the reference binary ($1).
 sources_newer() {
@@ -814,15 +827,27 @@ build_linux_binaries() {
   local cross_toolchain="${CROSS_RUST_TOOLCHAIN:-${host_toolchain:-stable}}"
   log "  1.3 linux build: cross-compiling aarch64-linux binaries (toolchain $cross_toolchain; first run is slow)…"
   local build_rc=0
+  # CARGO_TARGET_DIR points at a NAMED VOLUME (/cargo-target), NOT the host
+  # bind-mount — see the TARGET dir note above. After a successful build the
+  # three release binaries are copied OUT of the volume into the bind-mounted
+  # /src/target/sandbox-linux/release/ (= host $LINUX_TARGET_DIR/release) so the
+  # idempotency gate + upload step keep reading them from the same host path.
   docker run --rm --platform linux/arm64 \
     -v "$REPO_ROOT":/src -w /src \
     -v "$CARGO_REGISTRY_VOL":/usr/local/cargo/registry \
     -v "$CARGO_GIT_VOL":/usr/local/cargo/git \
     -v "$RUSTUP_VOL":/usr/local/rustup \
-    -e CARGO_TARGET_DIR=/src/target/sandbox-linux \
+    -v "$CARGO_TARGET_VOL":/cargo-target \
+    -e CARGO_TARGET_DIR=/cargo-target \
     -e RUSTUP_TOOLCHAIN="$cross_toolchain" \
     "$BUILDER_IMAGE" \
-    cargo build --release -p agentkeys-cli -p agentkeys-mcp-server -p agentkeys-daemon || build_rc=$?
+    bash -c 'set -e
+      cargo build --release -p agentkeys-cli -p agentkeys-mcp-server -p agentkeys-daemon
+      mkdir -p /src/target/sandbox-linux/release
+      cp -f /cargo-target/release/agentkeys \
+            /cargo-target/release/agentkeys-mcp-server \
+            /cargo-target/release/agentkeys-daemon \
+            /src/target/sandbox-linux/release/' || build_rc=$?
   # Check the BUILD EXIT CODE, not just file existence — a stale binary from a
   # prior build must not be mistaken for a fresh success (silent-failure trap).
   if [[ "$build_rc" -eq 0 && -x "$agent_bin" && -x "$mcp_bin" && -x "$daemon_bin" ]]; then
diff --git a/scripts/setup-broker-host.sh b/scripts/setup-broker-host.sh
index 798d6373..75d91cdf 100755
--- a/scripts/setup-broker-host.sh
+++ b/scripts/setup-broker-host.sh
@@ -38,7 +38,7 @@ CRED_MODE=""                 # set by interactive prompt or --cred-mode
 PROFILE_NAME="agentkeys-daemon"
 WITH_NGINX="yes"             # default: install + configure nginx (opt out via --without-nginx)
 WITH_CERTBOT="yes"           # default: install certbot (opt out via --without-certbot)
-ASSUME_YES=false
+ASSUME_YES=true              # unattended by default (script is idempotent). --yes/-y/--non-interactive/--interactive remain accepted no-ops for back-compat with CI + runbooks.
 TEST_MODE=false              # --test: suffix every derived hostname + bucket with "-test"
                              # so a single flag replaces the 8 explicit
                              # --signer-host / --vault-bucket / --email-from / etc.
@@ -60,8 +60,7 @@ MEMORY_BUCKET=""
 SCOPE_ADDR=""
 REGISTRY_ADDR=""
 K3_COUNTER_ADDR=""
-WITH_WORKERS="yes"           # --without-workers: skip build+install of the 4 service workers (audit/email/cred/memory)
-CLEAN_BROKER="auto"          # --clean: force `cargo clean -p` first; auto = self-heal only on assertion miss
+WITH_WORKERS="yes"           # in-file constant: the 4 service workers (audit/email/cred/memory) are core — always built+installed. The build is idempotent (skips up-to-date crates), so there is no operator opt-out flag to remember.
 # Verified SES sender for email-link auth. Operator must register this
 # identity via scripts/ses-verify-sender.sh BEFORE booting the broker;
 # the broker's verify_sender_ready precheck calls SES GetEmailIdentity
@@ -106,10 +105,7 @@ while (( $# > 0 )); do
     --scope-addr)         SCOPE_ADDR="$2"; shift 2 ;;
     --registry-addr)      REGISTRY_ADDR="$2"; shift 2 ;;
     --k3-counter-addr)    K3_COUNTER_ADDR="$2"; shift 2 ;;
-    --without-workers)    WITH_WORKERS="no"; shift ;;
     --email-from)         BROKER_EMAIL_FROM_ADDRESS="$2"; shift 2 ;;
-    --clean)              CLEAN_BROKER="yes"; shift ;;
-    --no-clean)           CLEAN_BROKER="no"; shift ;;
     -h|--help)
       sed -n '2,/^set -euo/p' "$0" | sed 's/^# \?//'
       exit 0
@@ -490,7 +486,7 @@ cat <<EOF
 This will:
   • install build deps + Rust toolchain (if missing)
   • build agentkeys-mock-server + agentkeys-broker-server in release mode
-  • build agentkeys-worker-{audit,email,creds,memory} in release mode (skip with --without-workers)
+  • build agentkeys-worker-{audit,email,creds,memory} in release mode
   • install all binaries to /usr/local/bin
   • create the 'agentkeys' system user + /var/lib/agentkeys (mode 0700)
   • drop systemd units for backend + broker + signer + 4 service workers
@@ -565,18 +561,12 @@ log "Building agentkeys-mock-server (release)"
 
 # Build agentkeys-broker-server with auth-email-link, asserting via
 # cargo's --message-format=json output that the feature is actually
-# enabled. Three modes for incremental-cache hygiene:
-#
-#   --clean       force `cargo clean -p agentkeys-broker-server --release`
-#                 before the build (3-5min full rebuild).
-#   --no-clean    never clean; trust incremental cache. Use when you
-#                 KNOW the cache is good and want the fastest re-deploy.
-#   (default)     auto: skip clean, run incremental build, ASSERT the
-#                 feature is in cargo's reported feature set; if NOT,
-#                 self-heal by running `cargo clean -p` and rebuilding
-#                 ONCE. Failing again is a real environment bug (host
-#                 .cargo/config.toml override, env-var pin, etc.) and
-#                 the script dies with 5 specific things to check.
+# enabled. Incremental-cache hygiene is fully automatic (no flag): run the
+# incremental build, ASSERT the feature is in cargo's reported feature set,
+# and if it is NOT, self-heal by running `cargo clean -p` and rebuilding
+# ONCE. Failing again is a real environment bug (host .cargo/config.toml
+# override, env-var pin, etc.) and the script dies with 5 specific things
+# to check.
 #
 # Critical: stdout (NDJSON) and stderr (compiler progress / errors) MUST
 # be redirected separately. Merging them with `2>&1` corrupts the NDJSON
@@ -622,19 +612,12 @@ assert_feature_enabled() {
   esac
 }
 
-if [[ "$CLEAN_BROKER" == "yes" ]]; then
-  log "cargo clean -p agentkeys-broker-server --release  (--clean requested)"
-  ( cd "$REPO_ROOT" && cargo clean -p agentkeys-broker-server --release ) \
-    || warn "cargo clean -p returned non-zero — continuing (may be a fresh tree)"
-fi
-
 build_broker_with_features
 
 log "Verifying broker binary has auth-email-link compiled in"
-if ! assert_feature_enabled && [[ "$CLEAN_BROKER" != "no" ]]; then
+if ! assert_feature_enabled; then
   warn "auth-email-link missing from cargo's reported features [$ENABLED_FEATURES]"
   warn "Self-healing: cargo clean -p + rebuild (one retry; ~3-5min)"
-  warn "Pass --no-clean to disable self-heal, or --clean to skip this and clean upfront."
   ( cd "$REPO_ROOT" && cargo clean -p agentkeys-broker-server --release ) \
     || warn "cargo clean -p returned non-zero — continuing"
   build_broker_with_features
@@ -649,10 +632,6 @@ if ! assert_feature_enabled && [[ "$CLEAN_BROKER" != "no" ]]; then
      5. cat $REPO_ROOT/Cargo.lock | head -5  (committed lockfile drift?)
    Then file a repro for the issue tracker."
   fi
-elif ! assert_feature_enabled; then
-  # --no-clean explicitly requested: don't self-heal, just die.
-  die "auth-email-link missing from cargo's reported features [$ENABLED_FEATURES] and --no-clean is set.
-   Re-run without --no-clean (or with --clean) to let the script self-heal."
 fi
 
 # Belt-and-suspenders: nm symbol-table check (more reliable than strings,
@@ -1595,7 +1574,7 @@ case "$agent_create_code" in
   401) log "  §10.2 /v1/agent/create live (401 unauth as expected — issue #144 routes deployed)" ;;
   404) die "POST /v1/agent/create → 404: the running broker binary predates issue #144 (§10.2 routes missing).
    The build/install did not deploy the new code. Fix:
-     rm -rf $REPO_ROOT/target/release/agentkeys-broker-server && re-run this script (--clean forces a clean rebuild)." ;;
+     rm -rf $REPO_ROOT/target/release/agentkeys-broker-server && re-run this script (it self-heals with a clean rebuild when the feature is missing)." ;;
   *)   warn "POST /v1/agent/create → HTTP $agent_create_code (expected 401). Route appears present; continuing (the /healthz probe already passed)." ;;
 esac
 
@@ -1608,6 +1587,25 @@ if [[ "$WITH_WORKERS" == "yes" ]]; then
   probe_or_die worker-memory 9095 agentkeys-worker-memory
 fi
 
+# ─── 8b. Hosted MCP endpoint (auto-converged, no flag; issue #152) ────────────
+# The broker-hosted agentkeys-mcp-server (--transport mcp-endpoint, behind nginx
+# TLS) is the HOSTED-LLM path — a remote vendor LLM (xiaozhi / Doubao) connects
+# INWARD over WSS — issue #152, deferred. There is NO flag to remember: behaviour
+# CONVERGES from state. If the hosted MCP was ever deployed on this host (its
+# binary is installed), every broker setup re-runs setup-mcp-host.sh to keep it
+# current (cached incremental `cargo build -p`, NOT `cargo install --git`,
+# against THIS checkout). On a host that never had it this is a clean no-op.
+# First-time enablement is #152 work; the Local-LLM / Task-agent wire demo never
+# needs it — that MCP server runs in the agent's own sandbox.
+if [[ -x /usr/local/bin/agentkeys-mcp-server ]]; then
+  MCP_TEST_FLAG=""
+  [[ "$TEST_MODE" == "true" ]] && MCP_TEST_FLAG="--test"
+  log "Hosted MCP present on this host — re-converging via setup-mcp-host.sh $MCP_TEST_FLAG"
+  ( cd "$REPO_ROOT" && bash scripts/setup-mcp-host.sh $MCP_TEST_FLAG )
+else
+  log "Hosted MCP not deployed here — skipping (issue #152 path; the wire demo's MCP runs in the sandbox)"
+fi
+
 # ─── 9. Print remaining manual steps ──────────────────────────────────────────
 cat <<EOF
 
diff --git a/scripts/setup-cloud.sh b/scripts/setup-cloud.sh
index fe42c4f7..a34b98f0 100755
--- a/scripts/setup-cloud.sh
+++ b/scripts/setup-cloud.sh
@@ -697,6 +697,11 @@ do_step_14() {
   ok "mail bucket policy applied"
 }
 
+# NOTE: currently UNUSED. Step 15's SSM bring-up of the MCP server was removed
+# (hosted MCP is a broker-host concern now, run via setup-mcp-host.sh — #152). Retained
+# for the #152 path IF the hosted endpoint is ever brought up via SSM
+# SendCommand from the laptop rather than ssh-broker.sh + setup-broker-host.sh.
+#
 # Step-15 precondition: the broker EC2 must be a REGISTERED SSM managed instance
 # before SendCommand, or AWS returns InvalidInstanceId / "not in a valid state".
 # The on-host amazon-ssm-agent only registers if the instance's role carries
@@ -765,123 +770,20 @@ ensure_ssm_managed() {
 }
 
 do_step_15() {
-  CUR_STEP=15; step "Bring up agentkeys-mcp-server on broker (via SSM)"
-  : "${INSTANCE_ID:?INSTANCE_ID missing — broker EC2 needs to exist (re-run step 4 first)}"
-
-  # Make the broker EC2 SSM-ready BEFORE SendCommand (self-heals the missing
-  # AmazonSSMManagedInstanceCore that bit both prod + test brokers). Idempotent.
-  ensure_ssm_managed
-
-  REPO_URL_FOR_MCP="${AGENTKEYS_REPO_URL:-https://github.com/litentry/agentKeys.git}"
-  REV_FOR_MCP="${AGENTKEYS_REV:-main}"
-  MCP_HOST_FLAGS=""
-  if [ "$TEST_MODE" = "1" ]; then
-    MCP_HOST_FLAGS="--test"
-  fi
-
-  if [ "$DRY_RUN" = "1" ]; then
-    warn "DRY: would SSM-run setup-mcp-host.sh on $INSTANCE_ID ($([ "$TEST_MODE" = "1" ] && echo test-mcp || echo mcp).${ZONE})"
-    return
-  fi
-
-  # The script body that runs on the broker. Idempotent — setup-mcp-host.sh
-  # short-circuits when state is already correct. Steps:
-  #   1. Ensure cargo (install rustup-minimal if missing — common on fresh EC2)
-  #   2. Clone or update the repo at /opt/agentkeys-src
-  #   3. Run scripts/setup-mcp-host.sh (which itself does `cargo install --git`)
-  local mcp_bring_up_script
-  mcp_bring_up_script=$(cat <<EOSH
-#!/usr/bin/env bash
-set -euo pipefail
-# SSM RunShellScript runs this as root with a MINIMAL env (no HOME). Under set -u
-# an unset \$HOME is a fatal "unbound variable", which broke step 15 the moment
-# SSM delivery started working. Default it before any \$HOME use (root => /root).
-export HOME="\${HOME:-/root}"
-export PATH="\$HOME/.cargo/bin:\$PATH"
-
-if ! command -v cargo >/dev/null 2>&1; then
-  curl -fsSL https://sh.rustup.rs | sh -s -- -y --default-toolchain stable --profile minimal
-  source "\$HOME/.cargo/env"
-fi
-
-REPO_DIR=/opt/agentkeys-src
-if [ ! -d "\$REPO_DIR/.git" ]; then
-  sudo install -d -m 0755 -o ubuntu -g ubuntu "\$REPO_DIR"
-  sudo -u ubuntu git clone --depth 1 -b ${REV_FOR_MCP} ${REPO_URL_FOR_MCP} "\$REPO_DIR"
-else
-  sudo -u ubuntu git -C "\$REPO_DIR" fetch --depth 1 origin ${REV_FOR_MCP}
-  sudo -u ubuntu git -C "\$REPO_DIR" reset --hard FETCH_HEAD
-fi
-
-cd "\$REPO_DIR"
-sudo -E AGENTKEYS_REPO_URL=${REPO_URL_FOR_MCP} AGENTKEYS_REV=${REV_FOR_MCP} \\
-  bash scripts/setup-mcp-host.sh ${MCP_HOST_FLAGS}
-EOSH
-)
-
-  local cmd_id _send_err
-  _send_err="$(mktemp)"
-  if ! cmd_id=$(aws ssm send-command \
-    --region "$REGION" \
-    --instance-ids "$INSTANCE_ID" \
-    --document-name "AWS-RunShellScript" \
-    --comment "agentkeys-mcp-server bring-up ($([ "$TEST_MODE" = "1" ] && echo test || echo prod))" \
-    --parameters "{\"commands\": $(jq -Rs . <<<"$mcp_bring_up_script" | jq -s .)}" \
-    --query "Command.CommandId" --output text 2>"$_send_err"); then
-    local _err; _err="$(cat "$_send_err" 2>/dev/null || true)"; rm -f "$_send_err"
-    # ensure_ssm_managed already verified the instance is registered, so a
-    # SendCommand AccessDenied here is a CALLER policy gap, not an instance one.
-    if printf '%s' "$_err" | grep -qiE 'accessdenied|not authorized|ssm:sendcommand'; then
-      die "ssm:SendCommand DENIED for your CALLER (identity-based policy gap — $INSTANCE_ID is SSM-registered, verified just above, so this is NOT an instance problem). Your operator IAM user needs ssm:SendCommand on the instance + the AWS-RunShellScript document, plus ssm:GetCommandInvocation/ListCommandInvocations. Grant it with \`aws iam put-user-policy\` on your user (see scripts/provision-ci-deploy-role.sh for the exact policy shape it grants the CI deploy role), then re-run. Detail: $_err"
-    fi
-    die "aws ssm send-command failed — does $INSTANCE_ID have amazon-ssm-agent + the SSM instance profile? Detail: $_err"
-  fi
-  rm -f "$_send_err"
-  ok "SSM command $cmd_id queued on $INSTANCE_ID; polling for completion (up to 25 min)"
-
-  # Poll every 10s for up to 25 min. setup-mcp-host.sh runs `cargo install --git`
-  # to build agentkeys-mcp-server FROM SOURCE; a COLD build on a t3.medium can
-  # take 10–20 min. The old 10-min cap timed out mid-build, and the silent poll
-  # (no per-iteration output) looked like a hang. Heartbeat ~every 30s so it's
-  # visibly alive, and on a genuine timeout the build is usually still running on
-  # the broker (not a failure) — re-running --from-step 15 resumes polling and
-  # the cargo cache makes that build finish fast.
-  local status="Pending" last=""
-  for i in $(seq 1 150); do
-    sleep 10
-    status=$(aws ssm get-command-invocation \
-      --region "$REGION" \
-      --command-id "$cmd_id" \
-      --instance-id "$INSTANCE_ID" \
-      --query "Status" --output text 2>/dev/null || echo "Pending")
-    case "$status" in
-      Success)
-        ok "MCP server brought up on $INSTANCE_ID"
-        # Tail the last 30 lines of stdout for a quick sanity check
-        aws ssm get-command-invocation \
-          --region "$REGION" --command-id "$cmd_id" --instance-id "$INSTANCE_ID" \
-          --query "StandardOutputContent" --output text 2>/dev/null \
-          | tail -30 | sed 's/^/      /' >&2 || true
-        return ;;
-      Failed|Cancelled|TimedOut)
-        warn "SSM command status: $status"
-        aws ssm get-command-invocation \
-          --region "$REGION" --command-id "$cmd_id" --instance-id "$INSTANCE_ID" \
-          --query "StandardErrorContent" --output text 2>/dev/null \
-          | tail -50 | sed 's/^/      /' >&2 || true
-        die "MCP bring-up failed; inspect: aws ssm get-command-invocation --region $REGION --command-id $cmd_id --instance-id $INSTANCE_ID --query StandardErrorContent --output text" ;;
-    esac
-    # Heartbeat on the first tick, on any status change, and ~every 30s, so a long
-    # cold cargo build is visibly alive rather than looking hung.
-    if [ "$status" != "$last" ] || [ $(( i % 3 )) -eq 1 ]; then
-      printf "    … MCP bring-up running: status=%s, ~%ds elapsed (cold cargo build ~10–20 min)\n" "$status" "$(( i * 10 ))" >&2
-      last="$status"
-    fi
-  done
-  die "MCP bring-up still '$status' after 25 min — the cargo build is most likely STILL RUNNING on the broker (not a failure). Re-run to resume polling (idempotent; the cargo cache makes the build finish fast):
-     bash scripts/setup-cloud.sh --from-step 15$([ "$TEST_MODE" = "1" ] && echo " --test" || echo "")
-   Or watch it directly:
-     aws ssm get-command-invocation --region $REGION --command-id $cmd_id --instance-id $INSTANCE_ID --query Status --output text"
+  CUR_STEP=15; step "Hosted MCP endpoint — removed from cloud setup (broker-host concern; issue #152)"
+  # The broker-hosted agentkeys-mcp-server (--transport mcp-endpoint, behind nginx
+  # TLS) is the HOSTED-LLM path (xiaozhi / vendor-cloud connects inward) — issue
+  # #152, deferred. It is a BROKER-HOST concern, not cloud/IAM: setup-cloud.sh is
+  # permission/IAM work under agentkeys-admin ONLY. The old body SSM-ran
+  # setup-mcp-host.sh on the broker, cloning `main` and cold-building via
+  # `cargo install --git` (~10–20 min EVERY run — no warm target/ cache). The
+  # build now lives where broker-host binaries belong — setup-mcp-host.sh on the
+  # broker (cached `cargo build -p` against THIS checkout, not a fresh clone of
+  # stale `main`); once it is deployed, setup-broker-host.sh re-converges it
+  # automatically (no flag to remember — issue #152).
+  skip "step 15 is a no-op now — the hosted MCP endpoint is the deferred #152 path and a broker-host concern, not cloud/IAM. The Local-LLM / Task-agent wire demo does NOT need it (its MCP server runs in the sandbox — harness/phase1-wire-demo.sh). When you work #152, enable it once on the broker; thereafter setup-broker-host.sh re-converges it automatically (no flag):
+       bash scripts/ssh-broker.sh $([ "$TEST_MODE" = "1" ] && echo test || echo prod)
+       sudo bash /opt/agentkeys-src/scripts/setup-mcp-host.sh$([ "$TEST_MODE" = "1" ] && echo " --test" || echo "")"
 }
 
 do_step_16() {
@@ -919,9 +821,8 @@ do_step_16() {
   printf "    bash scripts/setup-cloud.sh --only-step 6   # re-UPSERT DNS\n" >&2
   printf "    bash scripts/setup-cloud.sh --only-step 12  # re-create SSH user (e.g. after EC2 replace)\n" >&2
   printf "    bash scripts/setup-cloud.sh --only-step 13  # re-run per-data-class provisioning\n" >&2
-  printf "    bash scripts/setup-cloud.sh --only-step 15  # re-run the MCP bring-up on the broker via SSM (add --test for the test broker)\n" >&2
-  printf "    bash scripts/setup-cloud.sh --only-step 15  # re-deploy agentkeys-mcp-server on broker (cargo install --git)\n" >&2
-  printf "    bash scripts/setup-cloud.sh --only-step 15 --test  # same for test-mcp.\${ZONE}\n\n" >&2
+  printf "    # step 15 (hosted MCP on broker) moved OUT of cloud setup — it is a broker-host concern (issue #152).\n" >&2
+  printf "    # deploy it on the broker when needed:  setup-mcp-host.sh (idempotent); setup-broker-host.sh then re-converges it\n\n" >&2
 }
 
 main() {
diff --git a/scripts/setup-mcp-host.sh b/scripts/setup-mcp-host.sh
index 63d86072..4a66ca22 100755
--- a/scripts/setup-mcp-host.sh
+++ b/scripts/setup-mcp-host.sh
@@ -22,8 +22,10 @@
 #   https://mcp.litentry.org/mcp_endpoint/health?key=<KEY>   → 智控台 health
 #
 # Run ON the broker host (same host setup-broker-host.sh runs against).
-# Standalone for now; CLAUDE.md follow-up: fold into setup-broker-host.sh
-# as `--with-mcp` once this stabilises.
+# This is the first-time enable for the hosted MCP endpoint. Once the binary is
+# installed, setup-broker-host.sh AUTO-CONVERGES it on every run (re-invokes this
+# script to keep it current) — NO flag to remember; behaviour follows state
+# (issue #152).
 #
 # Usage (xiaozhi-hosted mode — DEFAULT, simpler):
 #   bash scripts/setup-mcp-host.sh --xiaozhi-endpoint 'wss://api.xiaozhi.me/mcp/?token=…'
@@ -71,7 +73,6 @@ XIAOZHI_ENDPOINT_FILE="${ENV_FILE_DIR}/mcp-xiaozhi-endpoint"
 MCP_BIN_DST="/usr/local/bin/agentkeys-mcp-server"
 WITH_NGINX="yes"
 WITH_CERTBOT="yes"
-WITH_BUILD="yes"
 CERTBOT_EMAIL=""
 TEST_MODE="no"
 DOMAIN_OVERRIDE=""
@@ -87,7 +88,6 @@ while [[ $# -gt 0 ]]; do
     --certbot-email)      CERTBOT_EMAIL="$2"; shift 2 ;;
     --without-nginx)      WITH_NGINX="no"; shift ;;
     --without-certbot)    WITH_CERTBOT="no"; shift ;;
-    --without-build)      WITH_BUILD="no"; shift ;;
     --relay-port)         RELAY_PORT="$2"; shift 2 ;;
     --relay-ref)          RELAY_PIN_REF="$2"; shift 2 ;;
     --help|-h)            sed -n '2,50p' "$0"; exit 0 ;;
@@ -189,7 +189,6 @@ echo "    mcp binary dst:    ${MCP_BIN_DST}" >&2
 echo "    mcp build:         cargo build --release -p agentkeys-mcp-server  (in ${REPO_ROOT}, cached/incremental)" >&2
 echo "    with nginx:        ${WITH_NGINX}" >&2
 echo "    with certbot:      ${WITH_CERTBOT}" >&2
-echo "    with build:        ${WITH_BUILD}" >&2
 
 # ─── 1. /etc/agentkeys exists with the right perms ───────────────────
 head "1/9 /etc/agentkeys layout"
@@ -334,27 +333,25 @@ fi  # MODE == self-hosted (closes step 3 self-hosted branch)
 #   AGENTKEYS_REV=my-pr-branch bash scripts/setup-mcp-host.sh
 head "4/9 build agentkeys-mcp-server (cached workspace build)"
 
-if [ "$WITH_BUILD" = "yes" ]; then
-  command -v cargo >/dev/null 2>&1 \
-    || fail "cargo not found — install Rust (curl https://sh.rustup.rs | sh) or pass --without-build if the binary is already at $MCP_BIN_DST"
-  # Build IN the on-host repo checkout ($REPO_ROOT, e.g. /opt/agentkeys-src) using
-  # its PERSISTENT target/ — NOT `cargo install --git`, which re-clones + builds
-  # the ENTIRE dep tree in a throwaway target every run (a ~10–20 min COLD build
-  # on the t3.medium broker). setup-broker-host.sh already compiled
-  # aws-sdk/tokio/k256/etc. into this same target/release, and the target persists
-  # across re-runs, so `cargo build -p` is INCREMENTAL — only the mcp-server crate
-  # recompiles (seconds–2 min). Same cached-build approach as setup-broker-host.sh
-  # and harness/phase1-wire-demo.sh. ($REPO_ROOT was already checked out to the
-  # desired ref by the caller — e.g. setup-cloud.sh step 15's clone/reset — so no
-  # separate `--git` fetch is needed; we build the code that's actually here.)
-  ok "cargo build --release -p agentkeys-mcp-server (in $REPO_ROOT, reusing the target/release cache)"
-  ( cd "$REPO_ROOT" && cargo build --release --locked -p agentkeys-mcp-server ) \
-    || fail "cargo build -p agentkeys-mcp-server failed in $REPO_ROOT"
-fi
+command -v cargo >/dev/null 2>&1 \
+  || fail "cargo not found — install Rust first (curl https://sh.rustup.rs | sh -s -- -y)"
+# Build IN the on-host repo checkout ($REPO_ROOT, e.g. /opt/agentkeys-src) using
+# its PERSISTENT target/ — NOT `cargo install --git`, which re-clones + builds
+# the ENTIRE dep tree in a throwaway target every run (a ~10–20 min COLD build
+# on the t3.medium broker). setup-broker-host.sh already compiled
+# aws-sdk/tokio/k256/etc. into this same target/release, and the target persists
+# across re-runs, so `cargo build -p` is INCREMENTAL — only the mcp-server crate
+# recompiles (seconds–2 min). Same cached-build approach as setup-broker-host.sh
+# and harness/phase1-wire-demo.sh. ($REPO_ROOT was already checked out to the
+# desired ref by the caller, so no separate `--git` fetch is needed; we build the
+# code that's actually here.)
+ok "cargo build --release -p agentkeys-mcp-server (in $REPO_ROOT, reusing the target/release cache)"
+( cd "$REPO_ROOT" && cargo build --release --locked -p agentkeys-mcp-server ) \
+  || fail "cargo build -p agentkeys-mcp-server failed in $REPO_ROOT"
 
 CACHED_BIN="$REPO_ROOT/target/release/agentkeys-mcp-server"
 if [ ! -x "$CACHED_BIN" ]; then
-  fail "$CACHED_BIN not built; drop --without-build or place the binary at $MCP_BIN_DST yourself"
+  fail "$CACHED_BIN not built (cargo build did not produce it)"
 fi
 
 src_sha=$(sha256sum "$CACHED_BIN" | awk '{print $1}')

From 218ca2e23965b05cbe70d4b52a9f6d57857ec460 Mon Sep 17 00:00:00 2001
From: Hanwen Cheng <heawen.cheng@gmail.com>
Date: Sun, 31 May 2026 22:01:23 +0800
Subject: [PATCH 12/23] docs(runbook): from-scratch bring-up order + explicit
 on-broker setup-broker-host.sh step

operator-runbook-wire.md now tells a from-nothing operator exactly what to run and ON WHICH MACHINE: (1) setup-cloud.sh on the laptop, (2) ssh-broker.sh + sudo setup-broker-host.sh --ref <branch> ON the broker host, (3) setup-heima.sh, (4) the harness. Explains the --ref branch choice (claude/impl-144-hdkd-bootstrap until #149 merges) and why a 'git pull' on main shows nothing (the work is on the feature branch). Keeps the re-run-only-what-changed table.

Refs #149.
---
 docs/operator-runbook-wire.md | 35 ++++++++++++++++++++++++-----------
 1 file changed, 24 insertions(+), 11 deletions(-)

diff --git a/docs/operator-runbook-wire.md b/docs/operator-runbook-wire.md
index bec0f6eb..2c8dc492 100644
--- a/docs/operator-runbook-wire.md
+++ b/docs/operator-runbook-wire.md
@@ -99,22 +99,35 @@ Note it puts the agent key back on the master; use only for quick loops.
 | **Proves** | the wire + hook + memory-injection **plumbing** works | the same, against **real IAM infra** (real signing + isolation) |
 | **Cost / risk** | free, can't break anything | real gas/cost, mutates real account state |
 
-## Setup entry points — run only what changed (idempotent, no flags to remember)
+## Setup entry points — first-time bring-up + re-runs
 
-`--light` needs none of this (it's self-contained). For `--real`, the live infra is owned by **three idempotent scripts — run only the one whose domain changed**, then re-run the harness:
+`--light` needs **none** of this (self-contained — skip to *How to run*). For **`--real`**, the live infra is owned by three idempotent scripts. **Run each ON the machine shown** — this is the part that bites: `setup-broker-host.sh` runs *on the broker host* (SSH in first), the other two from your laptop.
 
-| Script | Owns | Re-run when |
-|---|---|---|
-| [`scripts/setup-cloud.sh`](../scripts/setup-cloud.sh) | **Cloud / IAM only** (as `agentkeys-admin`) — SES, S3, DNS, roles, OIDC | a permission / role / DNS change |
-| [`scripts/setup-broker-host.sh`](../scripts/setup-broker-host.sh) | **The broker host** — broker + signer + 4 workers (binaries, systemd, nginx) | broker/worker code changed |
-| [`scripts/setup-heima.sh`](../scripts/setup-heima.sh) | **The chain** — contracts + per-actor binding ceremonies | a chain / contract change |
+### Starting from scratch (nothing set up yet) — run ONCE, in order
+
+| # | Run it on… | Command | Brings up |
+|---|---|---|---|
+| 1 | **laptop** (`agentkeys-admin` AWS profile) | `AWS_PROFILE=agentkeys-admin bash scripts/setup-cloud.sh` | Cloud/IAM: SES, S3, DNS, roles, OIDC, EC2 + EIP |
+| 2 | **the broker host** — SSH in first: `bash scripts/ssh-broker.sh` | `sudo bash scripts/setup-broker-host.sh --ref <branch>` | broker + signer + 4 workers (binaries, systemd, nginx/TLS) |
+| 3 | **laptop** | `bash scripts/setup-heima.sh` | chain: contracts + per-actor binding ceremonies |
+| 4 | **laptop** | `bash harness/phase1-wire-demo.sh --real --webauthn` | the demo itself |
+
+Notes:
+- **Step 1 prints these exact next-steps** when it finishes — it's the canonical source for the broker-host command (issuer URL + account ID filled in).
+- **Step 2 — which branch:** pass the branch you're deploying. Until [#149](https://github.com/litentry/agentKeys/pull/149) merges, that's **`--ref claude/impl-144-hdkd-bootstrap`**; after it merges, `--ref main`. `--ref` does the `git fetch` + checkout on the broker for you, so it builds the code you *mean* — not whatever happened to be checked out (this is why `git pull` on `main` didn't change anything: the work is on the feature branch). `--issuer-url` / `--account-id` auto-derive from the committed `scripts/operator-workstation.env`, so usually `--ref <branch>` is all you pass.
+- The broker MUST run the **#144 code** (the §10.2 `/v1/agent/*` routes) or Phase P fails with HTTP 404 — `--ref` guarantees that. The script self-checks (a no-bearer `POST /v1/agent/create` must return 401, not 404).
 
-All three are **idempotent and unattended by default** — a re-run with the same inputs converges and exits 0 without re-applying. There are **no opt-in/opt-out flags to remember**: behaviour follows state (workers always build but skip when up-to-date; the broker self-heals a bad feature build on its own). `--yes` / `--non-interactive` are still *accepted* (CI passes them) but are no longer needed.
+### Re-runs — only run the one whose domain changed
+
+| Script (where it runs) | Owns | Re-run when |
+|---|---|---|
+| [`scripts/setup-cloud.sh`](../scripts/setup-cloud.sh) — **laptop** | Cloud / IAM (SES, S3, DNS, roles, OIDC) | a permission / role / DNS change |
+| [`scripts/setup-broker-host.sh`](../scripts/setup-broker-host.sh) — **broker host** | broker + signer + 4 workers | broker/worker code changed |
+| [`scripts/setup-heima.sh`](../scripts/setup-heima.sh) — **laptop** | contracts + per-actor ceremonies | a chain / contract change |
 
-**The wire demo does NOT need a broker-hosted MCP server** — its MCP server runs **in the sandbox** (cross-built there once, then cached; see Prerequisites). The broker-hosted MCP endpoint is the *Hosted-LLM* path (xiaozhi / vendor-cloud), **deferred to [#152](https://github.com/litentry/agentKeys/issues/152)**; `setup-cloud.sh` step 15 is now a no-op that points there. So the right order to test the wire flow is just:
+All three are **idempotent + unattended by default** — re-running converges and exits 0 without re-applying; **no flags to remember** (workers always build but skip when up-to-date; the broker self-heals a bad feature build itself). `--yes` / `--non-interactive` are still *accepted* (CI passes them) but no longer needed.
 
-1. *(only if the matching infra above changed)* run that one script
-2. `bash harness/phase1-wire-demo.sh --real --webauthn`
+**The wire demo does NOT need a broker-hosted MCP server** — its MCP server runs **in the sandbox** (cross-built there once, then cached; see Prerequisites). The broker-hosted MCP endpoint is the *Hosted-LLM* path (xiaozhi / vendor-cloud), **deferred to [#152](https://github.com/litentry/agentKeys/issues/152)**; `setup-cloud.sh` step 15 is now a no-op pointing there.
 
 ## Prerequisites
 

From 67402ea71348fae1b0891955744a26375966e779 Mon Sep 17 00:00:00 2001
From: Hanwen Cheng <heawen.cheng@gmail.com>
Date: Sun, 31 May 2026 22:16:06 +0800
Subject: [PATCH 13/23] harness(pair): depair + re-pair each fresh run so P.2
 actually tests registerAgentDevice
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Before: AGENT_LABEL is stable + the sandbox K10 persisted, so P.2 hit the registerAgentDevice already-registered skip and the pairing path was never exercised ('ok ... or already-active'). The contract refuses to re-register a hash (registeredAt stays set even after revoke), so a real re-pair needs a NEW key.

Now, in fresh_pairing mode (--real without --reuse-agent): P.depair revokes the prior device (recorded as a PUBLIC-hash sidecar in the sandbox — key never leaves; heima-device-revoke.sh self-checks isActive + is idempotent, agent-tier so no Touch ID), wipes the sandbox K10 so P.1 mints a fresh key, and P.2 does a REAL registerAgentDevice. P.1 re-stashes the new hash for the next run's depair.

First run after this lands wipes the pre-existing ('hardcoded') key and registers fresh; that prior device stays an orphan (revoke it once by hand if you want it gone). Runbook tx-count notes updated (now ~2 txs/run: revoke + register).

Refs #149.
---
 docs/operator-runbook-wire.md |  9 ++++++---
 harness/phase1-wire-demo.sh   | 35 ++++++++++++++++++++++++++++-------
 2 files changed, 34 insertions(+), 10 deletions(-)

diff --git a/docs/operator-runbook-wire.md b/docs/operator-runbook-wire.md
index 2c8dc492..6342ebcb 100644
--- a/docs/operator-runbook-wire.md
+++ b/docs/operator-runbook-wire.md
@@ -24,7 +24,8 @@ bash harness/phase1-wire-demo.sh --light
 # mainnet. Runs a FRESH §10.2 pairing EACH run: the agent generates its own key
 # IN THE SANDBOX (never on the master), the master binds it on-chain, and
 # --webauthn "approves" the memory scope via Touch ID. Then it seeds + recalls
-# the Chengdu memory. Expect ONE Touch ID + one on-chain tx per run.
+# the Chengdu memory. Each run DEPAIRS the prior device (revoke) + re-pairs a fresh
+# K10 (register), so expect ONE Touch ID + ~2 on-chain txs per run.
 bash harness/phase1-wire-demo.sh --real --webauthn
 
 # VERIFY — deterministic, no LLM. Run IN THE SANDBOX after setup (the harness
@@ -44,8 +45,10 @@ is never ambiguous. Every step prints `ok proceeding` / `skip <reason>` /
 ## How to run — the `--real --webauthn` walkthrough
 
 One command runs the whole "install an app → approve its permissions → use it"
-story. Each run does a **fresh pairing** (a brand-new agent identity), so expect
-**one Touch ID + one on-chain tx per run**.
+story. Each run does a **genuine fresh pairing** — it **depairs** the prior device
+(on-chain revoke) and mints a **new K10 in the sandbox** for the same agent, so
+`registerAgentDevice` actually runs (not the already-registered skip). Expect
+**one Touch ID + ~2 on-chain txs (revoke + register) per run**.
 
 1. **Start the sandbox** (once — the harness checks but will not start it):
    ```bash
diff --git a/harness/phase1-wire-demo.sh b/harness/phase1-wire-demo.sh
index 947e177c..b8b350b0 100755
--- a/harness/phase1-wire-demo.sh
+++ b/harness/phase1-wire-demo.sh
@@ -496,14 +496,31 @@ phase1_sandbox() {
   # P.2+P.3 are ONE product approval conceptually; kept as two steps so the test
   # drives + verifies each deterministically. Skipped under --reuse-agent + --light.
   #
-  # IDEMPOTENT: AGENT_LABEL (default `demo-agent`) is stable, and the child omni is
-  # a deterministic HDKD of (O_master, label), so re-runs converge — the K10 file
-  # persists in the long-lived sandbox (clean_slate never wipes ~/.agentkeys), so
-  # registerAgentDevice hits the already-registered skip, the scope grant re-sets
-  # the same scope, the seed (1.5) overwrites, and the ack keeps `agent pending`
-  # self-cleaning. (Set AGENT_LABEL=demo-agent-$(date +%s) for a brand-new omni.)
+  # GENUINE FRESH PAIRING: AGENT_LABEL (default `demo-agent`) is stable and the
+  # child omni is a deterministic HDKD of (O_master, label). The persisted sandbox
+  # K10 used to make registerAgentDevice (P.2) hit the already-registered skip — so
+  # the pairing path was never actually exercised. We now DEPAIR + re-pair each run
+  # (P.depair below): revoke the prior on-chain device, wipe the sandbox K10 so P.1
+  # mints a NEW key, and P.2 does a REAL registerAgentDevice. The contract refuses
+  # to re-register a hash (registeredAt stays set even after revoke), so a fresh key
+  # is REQUIRED — depair alone would not let the same key re-register. Use
+  # --reuse-agent for a fast loop that skips pairing entirely.
   if [[ "$MODE" == "real" && "$REUSE_AGENT" != true ]]; then
     log "  Phase P — install (pair): §10.2 HDKD bootstrap (issue #144)"
+    # P.depair — guarantee a genuine fresh pairing. If a prior run recorded a
+    # device hash (sandbox sidecar — the hash is the PUBLIC on-chain id, never the
+    # key), revoke it (depair; agent-tier, no Touch ID; heima-device-revoke.sh
+    # self-checks isActive + is idempotent). Then wipe the sandbox K10 so P.1 mints
+    # a brand-new key and P.2 does a REAL registerAgentDevice instead of the
+    # already-registered skip. Custody holds: only the public hash leaves via the
+    # sidecar; the private key never leaves the sandbox.
+    local prior_dkh; prior_dkh="$(sbx_exec 'cat ~/.agentkeys/agent-device.hash 2>/dev/null' | tr -d '[:space:]')"
+    if [[ "$prior_dkh" == 0x* ]]; then
+      log "    P.depair: revoking prior device ${prior_dkh:0:14}… (idempotent — skips if already revoked) so this run re-pairs"
+      bash "$REPO_ROOT/scripts/heima-device-revoke.sh" --device-key-hash "$prior_dkh" 2>&1 | sed 's/^/        /' >&2 || true
+    fi
+    sbx_exec 'rm -f ~/.agentkeys/agent-device.key ~/.agentkeys/agent-device.hash' >/dev/null 2>&1 || true
+    ok "P.depair" "clean slate — sandbox K10 wiped; P.1 mints a fresh key, P.2 registers it for real"
     if [[ -z "$SESSION_BEARER" ]]; then
       fail "P.0 create" "no operator session bearer (0.7) — cannot mint a link code"
     else
@@ -547,6 +564,10 @@ phase1_sandbox() {
           fail "P.1 install" "redeemed omni ${ds_actor:0:14}… != created child ${child_omni:0:14}… (broker/derivation mismatch)"
         else
           ACTOR_OMNI="$ds_actor"; AGENT_SESSION_BEARER="$ds_jwt"; DEVICE_KEY_HASH="$ds_dkh"
+          # Record the (public) device hash in a sandbox sidecar so the NEXT fresh
+          # run can depair THIS exact device (P.depair). It's the on-chain id, not
+          # the key — custody is unaffected.
+          sbx_exec "printf '%s' '$ds_dkh' > ~/.agentkeys/agent-device.hash" >/dev/null 2>&1 || true
           ok "P.1 install" "📲 agent redeemed in-sandbox — addr ${ds_addr:0:12}…, omni ${ds_actor:0:14}… (K10 SANDBOX-only, J1_agent minted)"
           # P.1b master pulls the pending binding via `agentkeys agent pending` (the
           # rendezvous we built) and confirms THIS agent is awaiting approval.
@@ -564,7 +585,7 @@ phase1_sandbox() {
             --agent-address "$ds_addr" --actor-omni "$ds_actor" --device-key-hash "$ds_dkh" --pop-sig "$ds_pop" 2>&1)"
           echo "$reg" | sed 's/^/        /' >&2
           if echo "$reg" | grep -qiE '"ok"[[:space:]]*:[[:space:]]*true'; then
-            ok "P.2 bind" "on-chain registerAgentDevice (or already-active)"
+            ok "P.2 bind" "on-chain registerAgentDevice (fresh K10 from P.depair — a real registration, not the already-active skip)"
             # Ack the rendezvous: tell the broker the master bound this device so it
             # drops out of pending-bindings (self-cleaning → idempotent re-runs).
             curl -sS --max-time 15 -X POST "${BROKER_URL%/}/v1/agent/pending-bindings/ack" \

From f4d4cfadd6522860bc2d31d7952a197b9f7f4df1 Mon Sep 17 00:00:00 2001
From: Hanwen Cheng <heawen.cheng@gmail.com>
Date: Sun, 31 May 2026 22:45:32 +0800
Subject: [PATCH 14/23] docs(runbook): document P.depair in the walkthrough +
 reconcile fresh-device vs stable-omni
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The depair/re-pair was only in the TL;DR. Add P.depair to the 'What happens, in order' walkthrough, the Install-(pair) flag note, and the Phase-P troubleshooting row (which wrongly said 'the agent reuses its K10' — it now mints a fresh K10 each run).

Also reconcile the contradiction the depair surfaced: the label-derived omni is STABLE (same agent), only the device key is fresh — so memory persists and step 1.5 overwrites each run. Fixed the 'fresh/new agent identity ⇒ empty memory' wording in 4 spots.

Refs #149.
---
 docs/operator-runbook-wire.md | 17 +++++++++--------
 1 file changed, 9 insertions(+), 8 deletions(-)

diff --git a/docs/operator-runbook-wire.md b/docs/operator-runbook-wire.md
index 6342ebcb..3752bee2 100644
--- a/docs/operator-runbook-wire.md
+++ b/docs/operator-runbook-wire.md
@@ -62,12 +62,13 @@ story. Each run does a **genuine fresh pairing** — it **depairs** the prior de
    - **Phase 0** — prereqs + operator session (auto-minted from the master key).
    - **Phase 1** — sandbox up → Hermes installed → clean slate (1.2b) → binaries (re)built + uploaded (first build ~1 min).
    - **Phase P — install (pair)** 📲 (full §10.2 HDKD bootstrap, issue #144)
+     - `P.depair` — **genuine fresh pairing**: if a prior run left this agent's device paired, the master **revokes** it on-chain (depair; agent-tier, no biometric, idempotent) and the sandbox K10 is **wiped**. Required because the contract won't re-register a revoked hash (`registeredAt` sticks), so a real re-pair needs a brand-new key. Skipped under `--reuse-agent`.
      - `P.0` the **master** mints a one-time link code bound to the HDKD child omni `O_agent = SHA256(.. ‖ O_master ‖ "//label")` (real broker `/v1/agent/create`; no more `openssl` stub).
-     - `P.1` the **agent daemon** (`agentkeys-daemon --init-link-code`) generates its **own K10 device key in the sandbox**, proves possession, and **redeems** the code → `J1_agent` (the key never touches the master).
+     - `P.1` the **agent daemon** (`agentkeys-daemon --init-link-code`) generates a **fresh K10 device key in the sandbox** (P.depair wiped the old one), proves possession, and **redeems** the code → `J1_agent` (the key never touches the master).
      - `P.1b` the master pulls the rendezvous (`agentkeys agent pending`) and sees this agent awaiting approval.
-     - `P.2` the master **binds** that device **on-chain** (`registerAgentDevice`, no biometric) and **acks** the broker so it clears from `pending` (self-cleaning → idempotent re-runs).
+     - `P.2` the master **binds** that device **on-chain** — a **real `registerAgentDevice`** for the fresh key (no biometric), *not* the old already-registered skip — and **acks** the broker so it clears from `pending`.
      - `P.3` **🔐 Touch ID** — the master **grants** the agent's `[memory]` permission (`setScopeWithWebauthn`). Conceptually `P.2`+`P.3` are **one approval** (install + permissions, iOS/Android-style); kept as two steps for deterministic test automation.
-   - **1.4–1.5** — MCP server (per-actor STS relay) starts; the fresh actor's memory is seeded (new identity ⇒ empty ⇒ seeds "Chengdu trip").
+   - **1.4–1.5** — MCP server (per-actor STS relay) starts; step 1.5 (re)seeds the "Chengdu trip" fixture into the agent's memory namespace (keyed by the **stable** omni — only the device key is fresh — so 1.5 overwrites each run).
    - **Phase 2** — `agentkeys wire hermes` installs the IAM-gate hooks.
    - **Phase 4 — the surprise** — talk to Hermes and ask **"where am I going this weekend?"** → it recalls Chengdu (memory it *just earned permission to read*).
 4. **Talk to Hermes** for the surprise: open the printed `code-server` URL, or
@@ -92,9 +93,9 @@ Note it puts the agent key back on the master; use only for quick loops.
 | **In one line** | Self-contained sandbox demo — nothing external | The live product wired to real infra |
 | **MCP backend** | `in-memory` (data lives in the server's RAM) | `http` → real broker + workers |
 | **Memory data** | a **pre-seeded fixture** — the "Chengdu trip" is baked into the binary | the real S3-backed memory worker (empty unless you seeded it) |
-| **The Chengdu surprise** | ✅ works out of the box | ✅ **Phase P pairs + approves the scope (Touch ID), then 1.5 seeds** the fresh actor's memory — run **`--real --webauthn`**. The new agent identity starts with empty memory, so 1.5 always seeds it. Needs a live master session + K11 enrolled in webauthn mode |
+| **The Chengdu surprise** | ✅ works out of the box | ✅ **Phase P pairs + approves the scope (Touch ID), then 1.5 seeds** the agent's memory — run **`--real --webauthn`**. Step 1.5 (re)seeds the fixture each run — memory is keyed by the agent's **stable** omni (only the device key is fresh), so 1.5 overwrites and it's always present. Needs a live master session + K11 enrolled in webauthn mode |
 | **Broker / chain** | none | real broker (`signer.litentry.org`) + Heima **mainnet** |
-| **Account** | a fixed demo actor/operator | your master (operator) + a **fresh agent identity generated in the sandbox each run** (`--reuse-agent` reuses one master-side agent) |
+| **Account** | a fixed demo actor/operator | your master (operator) + the **same agent omni** (stable HDKD of the label) re-paired with a **fresh device key minted in the sandbox each run** (`--reuse-agent` reuses one master-side agent) |
 | **Cap-mint** | stubbed — always succeeds | real cap-mint (needs a valid master session) |
 | **Vendor token** | `demo-tok` | `harness-tok` |
 | **Touch ID** | never | at **Phase P (P.3)** EACH run when you pass `--webauthn` — the master *approves* the fresh agent's `[memory]` scope; never otherwise |
@@ -156,9 +157,9 @@ All three are **idempotent + unattended by default** — re-running converges an
 ## The manual gates (the "test through" essence)
 
 - **LLM key** — auto from `OPENROUTER_API_KEY` (or `LLM_API_KEY`); only prompts if absent. Phase 4.0 writes it to the sandbox `~/.hermes/.env` and sets `provider: openrouter` + `model.default` (default `deepseek/deepseek-v4-flash`; override `LLM_MODEL`). A non-fatal `4.1 model smoke` confirms the model is live before the surprise.
-- **Install (pair)** — `--real` only: **Phase P** — the master mints a one-time link code (`P.0`), the agent daemon (`agentkeys-daemon --init-link-code`) generates its device key **in the sandbox** + redeems it (`P.1`), the master binds it on-chain (`P.2`), and — with `--webauthn` — the master **approves** the agent's memory scope via Touch ID (`P.3`). Because every run pairs a **fresh** identity, this happens once per run. `--reuse-agent` skips it.
+- **Install (pair)** — `--real` only: **Phase P** — `P.depair` revokes any prior device + wipes the sandbox K10 so the re-pair is genuine, the master mints a one-time link code (`P.0`), the agent daemon (`agentkeys-daemon --init-link-code`) generates a **fresh** device key **in the sandbox** + redeems it (`P.1`), the master does a real `registerAgentDevice` (`P.2`), and — with `--webauthn` — the master **approves** the agent's memory scope via Touch ID (`P.3`). Every run depairs + re-pairs the same agent with a fresh device key (~2 on-chain txs). `--reuse-agent` skips all of Phase P.
 - **Real Touch ID** — in real mode with `--webauthn`: **Phase P (P.3)** grants the freshly-paired agent's memory scope via `heima-scope-set.sh --webauthn`. The banner prints `webauthn=<flag>` so you know upfront whether a Touch ID ceremony will run. It's a hardware prompt — `--yes` does NOT bypass it (it only auto-confirms the software "proceed?" gates). Without `--webauthn`, `P.3` is skipped (the agent won't be able to read memory) — re-run with `--real --webauthn`.
-- **Seed the real memory worker** (`--real` only) — after pairing, step **1.5** writes the Chengdu fixture into the fresh actor's namespace (a brand-new identity always starts empty). Override `SEED_MEMORY_CONTENT` / `SEED_SCOPE_SERVICES` (the latter is the service set Phase P grants — it **sets** the full list).
+- **Seed the real memory worker** (`--real` only) — after pairing, step **1.5** (re)writes the Chengdu fixture into the agent's memory namespace (keyed by the **stable** omni; 1.5 overwrites each run). Override `SEED_MEMORY_CONTENT` / `SEED_SCOPE_SERVICES` (the latter is the service set Phase P grants — it **sets** the full list).
 - **The Hermes surprise** — open Hermes in the sandbox, send "where am I going this weekend?", and judge the memory-aware reply (`[y/N]`).
 
 Pass `--yes` to auto-confirm the non-secret prompts.
@@ -249,7 +250,7 @@ Re-running `agentkeys wire hermes` is always safe — unchanged scripts/config s
 | cap-mint → 401 `ExpiredSignature` | the operator session JWT expired | the harness now auto-mints a fresh one at `0.7` via `wallet_sig` (`OPERATOR_KEY_FILE`). If it didn't: ensure `cast` is on PATH and `OPERATOR_KEY_FILE` exists |
 | cap-mint → 401/`OperatorMismatch` (`session_omni != operator_omni`) | the session is for a *different* operator (e.g. the legacy `alice` email session, omni `4231cd8f…` ≠ agent operator `941cb1c3…`) | `0.7` now detects the omni mismatch and re-mints from `OPERATOR_KEY_FILE`. If `0.7` fails with "wrong operator", point `OPERATOR_KEY_FILE` at the master key whose broker omni == `operator_omni` |
 | memory put/get → HTTP **502** `{"reason":"s3_put"}` / `{"reason":"s3_get"}` | the MCP `http` backend didn't forward per-actor STS creds, so the worker fell back to its EC2 instance profile (SES-only, **no S3**) → AccessDenied on every op. cap-mint + chain-verify themselves SUCCEED (the agent IS authorized); the gap was the credential **relay**. | **Fixed (issue #90):** the backend now mints agent-tagged STS creds (`0.8` agent session → broker `/v1/mint-oidc-jwt` → `AssumeRoleWithWebIdentity(memory-role)`, tagged `agentkeys_actor_omni`) and forwards them as `X-Aws-*` headers, so AWS scopes S3 to `bots/<actor>/memory/`. If it still 502s: confirm `P.1 install` shows "agent redeemed in-sandbox" (or `0.8 agent session` under `--reuse-agent`) and `P.3 grant` granted the scope; the relay needs the in-sandbox agent session + `MEMORY_ROLE_ARN`/`VAULT_ROLE_ARN`/`REGION` from `operator-workstation.env`. Optional strict enforcement: set `AGENTKEYS_WORKER_REQUIRE_STS=1` in the worker env (rejects credless requests with 401 instead of falling back). |
-| **Phase P** `P.0`/`P.1`/`P.2`/`P.3` fails | `P.0` create: broker `/v1/agent/create` down or the operator session (0.7) invalid. `P.1` install: stale sandbox `agentkeys-daemon` (no `--init-link-code`), broker `/v1/auth/link-code/redeem` down, or an expired link code (>600s). `P.2` bind: on-chain `registerAgentDevice` failed (master gas / RPC). `P.3` grant: `heima-scope-set --webauthn` needs K11 webauthn enrollment + Touch ID. | `P.0` check 0.7 + the broker. `P.1` 1.3 rebuilds+uploads the daemon binary — just re-run (the agent reuses its K10, so a retry is safe). `P.2` check the master wallet balance / RPC. `P.3` enroll K11 webauthn + pass `--webauthn`. For a quick loop without pairing use `--reuse-agent`. |
+| **Phase P** `P.depair`/`P.0`/`P.1`/`P.2`/`P.3` fails | `P.depair` revoke: master gas / RPC, or the sandbox unreachable for the K10 wipe. `P.0` create: broker `/v1/agent/create` down or the operator session (0.7) invalid. `P.1` install: stale sandbox `agentkeys-daemon` (no `--init-link-code`), broker `/v1/auth/link-code/redeem` down, or an expired link code (>600s). `P.2` bind: on-chain `registerAgentDevice` failed (master gas / RPC). `P.3` grant: `heima-scope-set --webauthn` needs K11 webauthn enrollment + Touch ID. | `P.depair`/`P.0` check 0.7 + the broker + master wallet balance. `P.1` 1.3 rebuilds+uploads the daemon binary — just re-run (each run mints a **fresh** K10, so a retry re-pairs cleanly). `P.2` check the master wallet balance / RPC. `P.3` enroll K11 webauthn + pass `--webauthn`. For a quick loop without pairing use `--reuse-agent`. |
 | `1.3 linux build` is slow even for a one-line change | (a) rustup re-downloaded the host-pinned toolchain (~250 MB, ~4 min) because `/usr/local/rustup` wasn't cached; (b) on macOS, cargo's `target/` sat on a **host bind-mount**, so every incremental file crossed the Docker VM's virtiofs layer | fixed on both: (a) the toolchain persists in `RUSTUP_VOL`; (b) `CARGO_TARGET_DIR` is now a **named volume** (`agentkeys-sandbox-target`) on the VM's native fs, with only the 3 final binaries copied out. First build seeds the caches (~4 min); later builds are incremental compile only (~15 s) |
 | Phase 1 `1.3 linux build` → "cannot pull" | Docker Hub unreachable for the base image | `RUST_BUILD_IMAGE=<local/mirror rust image>` or pre-pull `rust:1.83-slim-bookworm` |
 | `1.3 linux build` won't pick up a Rust edit | gate compares source mtime vs binary; re-runs rebuild automatically on a real edit | to force a from-scratch rebuild: `rm -rf target/sandbox-linux && docker volume rm agentkeys-sandbox-target agentkeys-sandbox-cargo-registry agentkeys-sandbox-cargo-git` (the `target/` dir now lives in the `agentkeys-sandbox-target` volume — `target/sandbox-linux` on the host holds only the 3 extracted binaries); to rebuild the deps image: `docker rmi agentkeys-sandbox-builder:1.83-bookworm` |

From 5f8051f054a90295aa5a0164aa61014aac85959b Mon Sep 17 00:00:00 2001
From: Hanwen Cheng <heawen.cheng@gmail.com>
Date: Sun, 31 May 2026 22:52:41 +0800
Subject: [PATCH 15/23] =?UTF-8?q?harness(P.0):=20on=20404,=20say=20'broker?=
 =?UTF-8?q?=20predates=20#144=20=E2=80=94=20redeploy'=20instead=20of=20a?=
 =?UTF-8?q?=20bare=20'no=20link=20code'?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

P.0 hitting the §10.2 routes on a stale broker returned a confusing 'agent/create returned no link code: HTTP 404'. Detect the 404 and name the exact fix (setup-broker-host.sh --ref claude/impl-144-hdkd-bootstrap on the broker) + the 401-not-404 verify. Notes that 1.4/1.5 are cascades. Refs #149.
---
 harness/phase1-wire-demo.sh | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/harness/phase1-wire-demo.sh b/harness/phase1-wire-demo.sh
index b8b350b0..7be3fa47 100755
--- a/harness/phase1-wire-demo.sh
+++ b/harness/phase1-wire-demo.sh
@@ -545,7 +545,15 @@ phase1_sandbox() {
       link_code="$(echo "$cr" | jq -r '.link_code // empty' 2>/dev/null)"
       child_omni="$(echo "$cr" | jq -r '.child_omni // empty' 2>/dev/null)"
       if [[ -z "$link_code" || -z "$child_omni" ]]; then
-        fail "P.0 create" "agent/create returned no link code: $(echo "$cr" | tr '\n' ' ' | cut -c1-200)"
+        if echo "$cr" | grep -q '404'; then
+          # The #1 P.0 trap: the DEPLOYED broker predates #144, so the §10.2
+          # routes (/v1/agent/create, /v1/auth/link-code/redeem,
+          # /v1/agent/pending-bindings) 404. The harness code is fine — the
+          # broker host just needs the #144/#149 binary. Name the fix loudly.
+          fail "P.0 create" "broker has NO §10.2 routes (HTTP 404) — the DEPLOYED broker predates #144. Redeploy it with the #144/#149 code FIRST: reach the broker with 'bash scripts/ssh-broker.sh', then on the host run 'sudo bash scripts/setup-broker-host.sh --ref claude/impl-144-hdkd-bootstrap'. Verify before re-running: a no-bearer 'POST ${BROKER_URL%/}/v1/agent/create' must return 401, not 404. (1.4 MCP + 1.5 seed below are cascades of this — they clear once P.0 works.)"
+        else
+          fail "P.0 create" "agent/create returned no link code: $(echo "$cr" | tr '\n' ' ' | cut -c1-200)"
+        fi
       else
         ok "P.0 create" "📇 master minted link code → child omni ${child_omni:0:14}… (label $AGENT_LABEL)"
         # P.1 agent generates K10 + redeems IN THE SANDBOX (daemon one-shot; key

From 02fb7c025f40dc018ee30ede974c941a81b60208 Mon Sep 17 00:00:00 2001
From: Hanwen Cheng <heawen.cheng@gmail.com>
Date: Sun, 31 May 2026 22:58:16 +0800
Subject: [PATCH 16/23] docs(runbook): don't git-pull by hand on the broker;
 --ref handles it + root-owned fix
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Operator hit 'unable to unlink … Permission denied' on a manual git pull because a prior 'sudo bash setup-broker-host.sh' ran git/cargo as root → root-owned repo. Note: use --ref (its git runs consistently), chown -R agentkey to restore manual git, and that the broker uses git not jj. Refs #149.
---
 docs/operator-runbook-wire.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/operator-runbook-wire.md b/docs/operator-runbook-wire.md
index 3752bee2..4dd14269 100644
--- a/docs/operator-runbook-wire.md
+++ b/docs/operator-runbook-wire.md
@@ -119,6 +119,7 @@ Note it puts the agent key back on the master; use only for quick loops.
 Notes:
 - **Step 1 prints these exact next-steps** when it finishes — it's the canonical source for the broker-host command (issuer URL + account ID filled in).
 - **Step 2 — which branch:** pass the branch you're deploying. Until [#149](https://github.com/litentry/agentKeys/pull/149) merges, that's **`--ref claude/impl-144-hdkd-bootstrap`**; after it merges, `--ref main`. `--ref` does the `git fetch` + checkout on the broker for you, so it builds the code you *mean* — not whatever happened to be checked out (this is why `git pull` on `main` didn't change anything: the work is on the feature branch). `--issuer-url` / `--account-id` auto-derive from the committed `scripts/operator-workstation.env`, so usually `--ref <branch>` is all you pass.
+- **Don't `git pull` by hand on the broker** — `--ref` does the fetch/checkout/pull. If a prior `sudo bash …` run left repo files **root-owned**, a manual `git pull` (as `agentkey`) dies with `error: unable to unlink old '…': Permission denied`. Just run `setup-broker-host.sh --ref …` (its git runs as root and replaces them); to restore manual git, run `sudo chown -R agentkey:agentkey ~/agentKeys` once. The broker uses plain **git**, not jj — jj is only for the laptop→origin push.
 - The broker MUST run the **#144 code** (the §10.2 `/v1/agent/*` routes) or Phase P fails with HTTP 404 — `--ref` guarantees that. The script self-checks (a no-bearer `POST /v1/agent/create` must return 401, not 404).
 
 ### Re-runs — only run the one whose domain changed

From c22f29936e3465108191e962d38bf5143ed50fab Mon Sep 17 00:00:00 2001
From: Hanwen Cheng <heawen.cheng@gmail.com>
Date: Sun, 31 May 2026 23:10:56 +0800
Subject: [PATCH 17/23] setup-broker-host: self-heal repo ownership when run
 via sudo (fixes git-pull Permission denied)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Running 'sudo bash setup-broker-host.sh' executes the script's plain git (--ref) + cargo as root, leaving root-owned files in the checkout that block the operator's next 'git pull' (error: unable to unlink … Permission denied). New §8c: when SUDO_USER is set, chown -R the repo back to the invoking user at the end — idempotent, scoped to $REPO_ROOT only (system files stay root/agentkeys-owned), no-op when run as the user directly or as root with no SUDO_USER (SSM/root-managed /opt clone). Runbook note updated. Refs #149.
---
 docs/operator-runbook-wire.md |  2 +-
 scripts/setup-broker-host.sh  | 16 ++++++++++++++++
 2 files changed, 17 insertions(+), 1 deletion(-)

diff --git a/docs/operator-runbook-wire.md b/docs/operator-runbook-wire.md
index 4dd14269..0532c3f3 100644
--- a/docs/operator-runbook-wire.md
+++ b/docs/operator-runbook-wire.md
@@ -119,7 +119,7 @@ Note it puts the agent key back on the master; use only for quick loops.
 Notes:
 - **Step 1 prints these exact next-steps** when it finishes — it's the canonical source for the broker-host command (issuer URL + account ID filled in).
 - **Step 2 — which branch:** pass the branch you're deploying. Until [#149](https://github.com/litentry/agentKeys/pull/149) merges, that's **`--ref claude/impl-144-hdkd-bootstrap`**; after it merges, `--ref main`. `--ref` does the `git fetch` + checkout on the broker for you, so it builds the code you *mean* — not whatever happened to be checked out (this is why `git pull` on `main` didn't change anything: the work is on the feature branch). `--issuer-url` / `--account-id` auto-derive from the committed `scripts/operator-workstation.env`, so usually `--ref <branch>` is all you pass.
-- **Don't `git pull` by hand on the broker** — `--ref` does the fetch/checkout/pull. If a prior `sudo bash …` run left repo files **root-owned**, a manual `git pull` (as `agentkey`) dies with `error: unable to unlink old '…': Permission denied`. Just run `setup-broker-host.sh --ref …` (its git runs as root and replaces them); to restore manual git, run `sudo chown -R agentkey:agentkey ~/agentKeys` once. The broker uses plain **git**, not jj — jj is only for the laptop→origin push.
+- **Don't `git pull` by hand on the broker** — `--ref` does the fetch/checkout/pull. A `sudo bash …` run executes the script's git+cargo as root, which would leave repo files **root-owned** (a later manual `git pull` as `agentkey` then dies with `error: unable to unlink old '…': Permission denied`) — but the script now **self-heals**: when invoked via sudo it chowns the checkout back to the invoking user at the end (§8c). For an already-stuck tree, a one-time `sudo chown -R agentkey:agentkey ~/agentKeys` clears it. The broker uses plain **git**, not jj — jj is only for the laptop→origin push.
 - The broker MUST run the **#144 code** (the §10.2 `/v1/agent/*` routes) or Phase P fails with HTTP 404 — `--ref` guarantees that. The script self-checks (a no-bearer `POST /v1/agent/create` must return 401, not 404).
 
 ### Re-runs — only run the one whose domain changed
diff --git a/scripts/setup-broker-host.sh b/scripts/setup-broker-host.sh
index 75d91cdf..1f1323f8 100755
--- a/scripts/setup-broker-host.sh
+++ b/scripts/setup-broker-host.sh
@@ -1606,6 +1606,22 @@ else
   log "Hosted MCP not deployed here — skipping (issue #152 path; the wire demo's MCP runs in the sandbox)"
 fi
 
+# ─── 8c. Self-heal repo ownership (idempotent) ───────────────────────────────
+# Root cause of "git pull → unable to unlink … Permission denied": when this
+# script is invoked via `sudo bash …`, its plain git (--ref) + cargo build run as
+# ROOT and leave root-owned files in the checkout, blocking the operator's next
+# `git pull`. If we were sudo'd, chown the checkout back to the invoking user so
+# manual git keeps working. Scoped to $REPO_ROOT only — system files under
+# /usr/local/bin, /etc/agentkeys, /var/lib/agentkeys stay root/agentkeys-owned.
+# No-op when run directly as the user (SUDO_USER unset) or as root with no
+# invoking user (e.g. SSM RunShellScript on the root-managed /opt clone).
+if [[ -n "${SUDO_USER:-}" && "$SUDO_USER" != "root" ]]; then
+  _repo_grp="$(id -gn "$SUDO_USER" 2>/dev/null || echo "$SUDO_USER")"
+  if sudo chown -R "$SUDO_USER:$_repo_grp" "$REPO_ROOT" 2>/dev/null; then
+    log "ownership: $REPO_ROOT chowned back to $SUDO_USER:$_repo_grp (so manual git keeps working)"
+  fi
+fi
+
 # ─── 9. Print remaining manual steps ──────────────────────────────────────────
 cat <<EOF
 

From c27678a08a19f171585351e404e4efb1be76363f Mon Sep 17 00:00:00 2001
From: Hanwen Cheng <heawen.cheng@gmail.com>
Date: Sun, 31 May 2026 23:30:01 +0800
Subject: [PATCH 18/23] harness(pair): fail-loud P.depair/P.2 instead of
 false-passing a fresh registration (Codex finding #3)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

P.depair swallowed revoke + K10-wipe failures with '|| true' then unconditionally reported 'clean slate', and P.2 grepped only '"ok":true' — which heima-agent-create.sh also returns for the already-registered SKIP (no tx_hash). So a stale-sidecar / unreachable-sandbox / failed-revoke run could greenlight 'a real registration' while only exercising the already-active path.

Now: (1) P.depair hard-fails if revoke is not ok:true, and confirms the sandbox K10 is actually gone (test -e) before claiming a clean slate; (2) P.1 hard-fails if the new device_key_hash == the prior sidecar hash (wipe didn't take); (3) P.2 distinguishes skipped:already-registered (FAIL — not a real registration) from a real tx_hash (ok) before acking. Refs #149.
---
 harness/phase1-wire-demo.sh | 28 ++++++++++++++++++++++++----
 1 file changed, 24 insertions(+), 4 deletions(-)

diff --git a/harness/phase1-wire-demo.sh b/harness/phase1-wire-demo.sh
index 7be3fa47..50f9eb3b 100755
--- a/harness/phase1-wire-demo.sh
+++ b/harness/phase1-wire-demo.sh
@@ -517,10 +517,26 @@ phase1_sandbox() {
     local prior_dkh; prior_dkh="$(sbx_exec 'cat ~/.agentkeys/agent-device.hash 2>/dev/null' | tr -d '[:space:]')"
     if [[ "$prior_dkh" == 0x* ]]; then
       log "    P.depair: revoking prior device ${prior_dkh:0:14}… (idempotent — skips if already revoked) so this run re-pairs"
-      bash "$REPO_ROOT/scripts/heima-device-revoke.sh" --device-key-hash "$prior_dkh" 2>&1 | sed 's/^/        /' >&2 || true
+      local rev; rev="$(bash "$REPO_ROOT/scripts/heima-device-revoke.sh" --device-key-hash "$prior_dkh" 2>&1)"
+      echo "$rev" | sed 's/^/        /' >&2
+      # heima-device-revoke.sh emits {"ok":true,…} on a real revoke AND on its
+      # idempotent already-revoked/not-active skip. ANYTHING else (gas, RPC, auth)
+      # is a HARD fail — proceeding would re-pair on a still-active device and the
+      # "real registration" claim below would be a lie.
+      if ! echo "$rev" | grep -qiE '"ok"[[:space:]]*:[[:space:]]*true'; then
+        fail "P.depair" "revoke of prior device $prior_dkh did NOT succeed — refusing to claim a clean slate: $(echo "$rev" | tr '\n' ' ' | cut -c1-160)"
+        return
+      fi
     fi
+    # Wipe the sandbox K10, then CONFIRM it's gone. If the sandbox is unreachable
+    # the rm silently no-ops, P.1 reuses the old key, and P.2 hits the already-
+    # active skip — so verify absence before claiming a clean slate.
     sbx_exec 'rm -f ~/.agentkeys/agent-device.key ~/.agentkeys/agent-device.hash' >/dev/null 2>&1 || true
-    ok "P.depair" "clean slate — sandbox K10 wiped; P.1 mints a fresh key, P.2 registers it for real"
+    if [[ -n "$(sbx_exec 'test -e ~/.agentkeys/agent-device.key && echo EXISTS' 2>/dev/null | tr -d '[:space:]')" ]]; then
+      fail "P.depair" "could not wipe the sandbox K10 (~/.agentkeys/agent-device.key still present — sandbox unreachable?); P.1 would reuse the old key → no fresh registration"
+      return
+    fi
+    ok "P.depair" "clean slate — prior device revoked + sandbox K10 wiped (confirmed); P.1 mints a fresh key"
     if [[ -z "$SESSION_BEARER" ]]; then
       fail "P.0 create" "no operator session bearer (0.7) — cannot mint a link code"
     else
@@ -570,6 +586,8 @@ phase1_sandbox() {
           fail "P.1 install" "in-sandbox daemon redeem failed: $(echo "$ds" | tr '\n' ' ' | cut -c1-200)"
         elif [[ "$ds_actor" != "$child_omni" ]]; then
           fail "P.1 install" "redeemed omni ${ds_actor:0:14}… != created child ${child_omni:0:14}… (broker/derivation mismatch)"
+        elif [[ -n "$prior_dkh" && "$ds_dkh" == "$prior_dkh" ]]; then
+          fail "P.1 install" "fresh pairing produced the SAME device_key_hash as the prior run ($ds_dkh) — the P.depair K10 wipe did not take; this is NOT a genuine re-pair"
         else
           ACTOR_OMNI="$ds_actor"; AGENT_SESSION_BEARER="$ds_jwt"; DEVICE_KEY_HASH="$ds_dkh"
           # Record the (public) device hash in a sandbox sidecar so the NEXT fresh
@@ -592,8 +610,10 @@ phase1_sandbox() {
           local reg; reg="$(bash "$REPO_ROOT/scripts/heima-agent-create.sh" --label "$AGENT_LABEL" \
             --agent-address "$ds_addr" --actor-omni "$ds_actor" --device-key-hash "$ds_dkh" --pop-sig "$ds_pop" 2>&1)"
           echo "$reg" | sed 's/^/        /' >&2
-          if echo "$reg" | grep -qiE '"ok"[[:space:]]*:[[:space:]]*true'; then
-            ok "P.2 bind" "on-chain registerAgentDevice (fresh K10 from P.depair — a real registration, not the already-active skip)"
+          if echo "$reg" | grep -qiE '"skipped"[[:space:]]*:[[:space:]]*"already-registered"'; then
+            fail "P.2 bind" "registerAgentDevice was SKIPPED (already-registered) — P.depair/P.1 did NOT yield a fresh device, so the pairing path was NOT exercised (check P.depair revoke + sandbox wipe): $(echo "$reg" | tr '\n' ' ' | cut -c1-160)"
+          elif echo "$reg" | jq -e '.ok==true and ((.tx_hash // "") != "")' >/dev/null 2>&1; then
+            ok "P.2 bind" "on-chain registerAgentDevice — REAL tx $(echo "$reg" | jq -r '.tx_hash' 2>/dev/null | cut -c1-18)… (fresh K10 from P.depair)"
             # Ack the rendezvous: tell the broker the master bound this device so it
             # drops out of pending-bindings (self-cleaning → idempotent re-runs).
             curl -sS --max-time 15 -X POST "${BROKER_URL%/}/v1/agent/pending-bindings/ack" \

From b5f55c9b49d02e77f10336b31b96a237bc3058e1 Mon Sep 17 00:00:00 2001
From: Hanwen Cheng <heawen.cheng@gmail.com>
Date: Sun, 31 May 2026 23:49:00 +0800
Subject: [PATCH 19/23] broker(oidc): gate mint-oidc-jwt for agent_hdkd
 sessions on on-chain device-active (Codex finding #1)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

mint_oidc_jwt accepted ANY valid session and signed an AssumeRoleWithWebIdentity JWT with no binding/scope check. Since /v1/auth/link-code/redeem mints J1_agent pre-binding, a redeemed-but-unapproved agent could get STS creds to its own actor prefix before the master's registerAgentDevice.

Now: an agent_hdkd session (device_pubkey present) must pass the SAME on-chain SidecarRegistry.getDevice check the cap-mint path uses — registered_at!=0, !revoked, and device.actor_omni == session omni — or it gets 403 (audited as AuthFailed). Wallet/master sessions (no device_pubkey) are unaffected. cap.rs ChainContracts/DeviceEntry/call_get_device exposed pub(crate) for reuse. cargo test -p agentkeys-broker-server green. Refs #149.
---
 .../src/handlers/cap.rs                       | 18 ++++----
 .../src/handlers/oidc.rs                      | 42 +++++++++++++++++++
 2 files changed, 51 insertions(+), 9 deletions(-)

diff --git a/crates/agentkeys-broker-server/src/handlers/cap.rs b/crates/agentkeys-broker-server/src/handlers/cap.rs
index 01cde9b7..297ce809 100644
--- a/crates/agentkeys-broker-server/src/handlers/cap.rs
+++ b/crates/agentkeys-broker-server/src/handlers/cap.rs
@@ -323,9 +323,9 @@ async fn mint_cap(
 const ROLE_CAP_MINT: u8 = 1;
 
 #[derive(Debug)]
-struct ChainContracts {
-    rpc_url: String,
-    registry: String,
+pub(crate) struct ChainContracts {
+    pub(crate) rpc_url: String,
+    pub(crate) registry: String,
     scope: String,
     epoch: String,
 }
@@ -336,7 +336,7 @@ impl ChainContracts {
     /// uppercased chain name with `-` → `_`. Matches the shape used in
     /// scripts/operator-workstation.env so broker/worker/CLI/bash all
     /// read the same value.
-    fn from_state(_state: &SharedState) -> Result<Self, CapError> {
+    pub(crate) fn from_state(_state: &SharedState) -> Result<Self, CapError> {
         let profile = std::env::var("AGENTKEYS_CHAIN").unwrap_or_else(|_| "heima".into());
         let profile_uc = profile.to_uppercase().replace('-', "_");
         let rpc_url = std::env::var("AGENTKEYS_CHAIN_RPC_HTTP")
@@ -363,12 +363,12 @@ fn profile_env(profile_uc: &str, base: &str) -> Result<String, CapError> {
 }
 
 #[derive(Debug)]
-struct DeviceEntry {
+pub(crate) struct DeviceEntry {
     operator_omni: String, // hex without 0x
-    actor_omni: String,
+    pub(crate) actor_omni: String,
     roles: u8,
-    registered_at: u64,
-    revoked: bool,
+    pub(crate) registered_at: u64,
+    pub(crate) revoked: bool,
 }
 
 async fn eth_call(
@@ -402,7 +402,7 @@ async fn eth_call(
         .ok_or_else(|| CapError::ChainRpc("eth_call missing 'result'".into()))
 }
 
-async fn call_get_device(
+pub(crate) async fn call_get_device(
     http: &reqwest::Client,
     rpc: &str,
     registry: &str,
diff --git a/crates/agentkeys-broker-server/src/handlers/oidc.rs b/crates/agentkeys-broker-server/src/handlers/oidc.rs
index 321cad17..83d27ee2 100644
--- a/crates/agentkeys-broker-server/src/handlers/oidc.rs
+++ b/crates/agentkeys-broker-server/src/handlers/oidc.rs
@@ -111,6 +111,48 @@ pub async fn mint_oidc_jwt(
     };
     tracing::Span::current().record("wallet", report_id.as_str());
 
+    // Finding 1 (adversarial review of #149): an agent_hdkd session (device_pubkey
+    // present, wallet empty) must NOT mint STS-capable OIDC JWTs until its device is
+    // bound on-chain. J1_agent is minted at link-code redeem (PRE-binding), so
+    // without this gate a redeemed-but-unapproved agent could AssumeRoleWithWebIdentity
+    // to its own actor prefix BEFORE the master's registerAgentDevice + scope grant.
+    // Wallet/master sessions (no device_pubkey) are the operator's own and unaffected.
+    // Same on-chain check the cap-mint path uses (SidecarRegistry.getDevice).
+    if let Some(device_pubkey) = session_claims.agentkeys.device_pubkey.as_deref() {
+        use crate::handlers::cap::{call_get_device, ChainContracts};
+        let chain = ChainContracts::from_state(&state)
+            .map_err(|e| BrokerError::Internal(format!("chain config for agent gate: {e:?}")))?;
+        let dkh = agentkeys_core::device_crypto::device_key_hash(device_pubkey)
+            .map_err(|e| BrokerError::BadRequest(format!("bad device_pubkey in session claim: {e}")))?;
+        let device = call_get_device(&state.http, &chain.rpc_url, &chain.registry, &dkh)
+            .await
+            .map_err(|e| BrokerError::Internal(format!("on-chain device read: {e:?}")))?;
+        let denied: Option<&str> = if device.registered_at == 0 || device.revoked {
+            Some("agent device not active on-chain — the master must registerAgentDevice (bind) before this agent can mint OIDC/STS credentials")
+        } else if device.actor_omni.to_lowercase()
+            != actor_omni.trim_start_matches("0x").to_lowercase()
+        {
+            Some("session omni does not match the on-chain device's actor_omni")
+        } else {
+            None
+        };
+        if let Some(reason) = denied {
+            let _ = state.audit.record_mint(
+                MintRecord {
+                    requester_token: token,
+                    requester_wallet: &report_id,
+                    requested_role: "oidc_jwt",
+                    session_duration_seconds: state.config.oidc_jwt_ttl_seconds as i32,
+                    sts_session_name: "(agent-not-active)",
+                    outcome: MintOutcome::AuthFailed,
+                },
+                Some(reason),
+            );
+            tracing::Span::current().record("outcome", "agent_not_active");
+            return Err(BrokerError::Forbidden(reason.into()));
+        }
+    }
+
     let (claims, _now, exp) = build_oidc_jwt_claims(
         &state.config.oidc_issuer,
         &actor_omni,

From 210a05119b59a34fe4cf5d0836c47784054a1eba Mon Sep 17 00:00:00 2001
From: Hanwen Cheng <heawen.cheng@gmail.com>
Date: Sun, 31 May 2026 23:49:17 +0800
Subject: [PATCH 20/23] daemon/mcp/harness: keep the agent bearer in the
 sandbox via owner-only file (Codex finding #2)

The daemon's --init-link-code printed session_jwt in its stdout artifact; the harness captured it on the master and passed it to the sandbox MCP as --agent-session-bearer (a CLI arg), exposing the bearer in the master shell + the sandbox process list (ps), readable by co-resident untrusted code.

Now: the daemon writes J1_agent to an owner-only ~/.agentkeys/agent-session.jwt (0600) and emits the PUBLIC session_file path instead of the JWT. The MCP server reads the bearer from --agent-session-bearer-file (env MCP_AGENT_SESSION_BEARER_FILE); a direct --agent-session-bearer still wins when set. The harness (fresh-pairing) passes the file path, never the value; --reuse-agent keeps the value path. Bearer now travels daemon->file->MCP entirely in the sandbox. K10 private-key custody was already intact; this closes the derived-bearer leak. cargo build (broker+daemon+mcp) green; bash -n clean. Refs #149.
---
 crates/agentkeys-daemon/src/main.rs       | 16 +++++++++++-
 crates/agentkeys-mcp-server/src/config.rs | 32 ++++++++++++++++++++++-
 harness/phase1-wire-demo.sh               | 31 ++++++++++++++++------
 3 files changed, 69 insertions(+), 10 deletions(-)

diff --git a/crates/agentkeys-daemon/src/main.rs b/crates/agentkeys-daemon/src/main.rs
index 19f6bf0d..9cd9be2e 100644
--- a/crates/agentkeys-daemon/src/main.rs
+++ b/crates/agentkeys-daemon/src/main.rs
@@ -526,6 +526,20 @@ async fn run_link_code_bootstrap(args: Args, link_code: &str) -> anyhow::Result<
         .unwrap_or_else(|| format!("daemon-{child_omni}"));
     session_store::save_session(&sess, &sid).context("save link-code session")?;
 
+    // Finding 2 (adversarial review): keep the bearer IN the sandbox. Write the
+    // session JWT to an owner-only (0600) file that the in-sandbox MCP server reads
+    // directly via --agent-session-bearer-file, and DO NOT print it on stdout — the
+    // master captures stdout and would otherwise expose the bearer in its shell +
+    // the sandbox process list (`ps`). Only PUBLIC binding fields leave the box.
+    let session_file = {
+        let home = std::env::var("HOME").unwrap_or_else(|_| "/root".to_string());
+        let dir = format!("{home}/.agentkeys");
+        std::fs::create_dir_all(&dir).ok();
+        format!("{dir}/agent-session.jwt")
+    };
+    agentkeys_core::device_crypto::write_key_0600(&session_file, session_jwt)
+        .context("persist agent session jwt (0600)")?;
+
     info!(
         target: "agentkeys.daemon.init",
         child_omni = %child_omni,
@@ -547,7 +561,7 @@ async fn run_link_code_bootstrap(args: Args, link_code: &str) -> anyhow::Result<
             "derivation_path": derivation_path,
             "device_key_hash": device_key_hash,
             "pop_sig": pop_sig,
-            "session_jwt": session_jwt,
+            "session_file": session_file,
             "link_code": link_code,
             "key_file": key_file,
         })
diff --git a/crates/agentkeys-mcp-server/src/config.rs b/crates/agentkeys-mcp-server/src/config.rs
index 048d7190..72ac8279 100644
--- a/crates/agentkeys-mcp-server/src/config.rs
+++ b/crates/agentkeys-mcp-server/src/config.rs
@@ -89,6 +89,14 @@ pub struct Cli {
     #[arg(long, env = "MCP_AGENT_SESSION_BEARER")]
     pub agent_session_bearer: Option<String>,
 
+    /// Path to an owner-only file containing the agent session JWT. Preferred
+    /// over --agent-session-bearer: the in-sandbox daemon (`--init-link-code`)
+    /// writes the bearer here (0600) so it never transits the master's shell or
+    /// the process list (adversarial-review finding #2). Used only when
+    /// --agent-session-bearer is not set directly.
+    #[arg(long, env = "MCP_AGENT_SESSION_BEARER_FILE")]
+    pub agent_session_bearer_file: Option<String>,
+
     /// Per-data-class IAM role ARN the worker S3 op assumes via web-identity.
     /// memory ops → memory_role_arn; credential ops → vault_role_arn.
     #[arg(long, env = "MCP_MEMORY_ROLE_ARN")]
@@ -211,6 +219,28 @@ impl Config {
                 )
             };
 
+        // Finding 2 (adversarial review): prefer the owner-only bearer FILE (the
+        // in-sandbox daemon writes it 0600) over an inline bearer, so the JWT never
+        // rides the CLI/process list or the master's shell. A direct
+        // --agent-session-bearer still wins when explicitly set.
+        let agent_session_bearer = match cli.agent_session_bearer {
+            Some(b) => Some(b),
+            None => match cli.agent_session_bearer_file.as_deref() {
+                Some(path) => {
+                    let raw = std::fs::read_to_string(path).map_err(|e| {
+                        anyhow::anyhow!("read --agent-session-bearer-file {path}: {e}")
+                    })?;
+                    let trimmed = raw.trim().to_string();
+                    if trimmed.is_empty() {
+                        None
+                    } else {
+                        Some(trimmed)
+                    }
+                }
+                None => None,
+            },
+        };
+
         Ok(Self {
             transport,
             backend,
@@ -224,7 +254,7 @@ impl Config {
             default_actor,
             default_operator_omni,
             default_device_key_hash,
-            agent_session_bearer: cli.agent_session_bearer,
+            agent_session_bearer,
             memory_role_arn: cli.memory_role_arn,
             vault_role_arn: cli.vault_role_arn,
             aws_region: cli.aws_region,
diff --git a/harness/phase1-wire-demo.sh b/harness/phase1-wire-demo.sh
index 50f9eb3b..3cd5e1a9 100755
--- a/harness/phase1-wire-demo.sh
+++ b/harness/phase1-wire-demo.sh
@@ -82,6 +82,11 @@ SESSION_BEARER="${AGENTKEYS_SESSION_BEARER:-}"
 # In fresh §10.2 pairing it is minted IN THE SANDBOX by Phase P; legacy 0.8 mints
 # it on the master (only under --reuse-agent).
 AGENT_SESSION_BEARER="${AGENTKEYS_AGENT_SESSION_BEARER:-}"
+# Finding 2 (adversarial review): fresh-pairing passes the agent bearer to the
+# in-sandbox MCP by FILE PATH (the daemon writes it 0600 in the sandbox), so the
+# JWT never transits the master shell or the process list. --reuse-agent still
+# uses the value it mints on the master.
+AGENT_SESSION_FILE=""
 # Fresh §10.2 pairing (DEFAULT in --real): the agent generates its OWN device key
 # in the sandbox each run (key never on the master). --reuse-agent (or
 # AGENTKEYS_REUSE_AGENT=1) falls back to the legacy master-side agent file.
@@ -575,21 +580,21 @@ phase1_sandbox() {
         # P.1 agent generates K10 + redeems IN THE SANDBOX (daemon one-shot; key
         # never on the master). 2>/dev/null drops the daemon's stderr logs so
         # stdout is clean artifact JSON for jq.
-        local ds ds_addr ds_actor ds_dkh ds_pop ds_jwt
+        local ds ds_addr ds_actor ds_dkh ds_pop ds_session_file
         ds="$(sbx_exec "$DAEMON_BIN_DST --init-link-code $link_code --broker-url ${BROKER_URL:-} 2>/dev/null")"
         ds_addr="$(echo "$ds" | jq -r '.agent_address // empty' 2>/dev/null)"
         ds_actor="$(echo "$ds" | jq -r '.actor_omni // empty' 2>/dev/null)"
         ds_dkh="$(echo "$ds" | jq -r '.device_key_hash // empty' 2>/dev/null)"
         ds_pop="$(echo "$ds" | jq -r '.pop_sig // empty' 2>/dev/null)"
-        ds_jwt="$(echo "$ds" | jq -r '.session_jwt // empty' 2>/dev/null)"
-        if [[ -z "$ds_jwt" || -z "$ds_actor" || -z "$ds_addr" || -z "$ds_dkh" || -z "$ds_pop" ]]; then
+        ds_session_file="$(echo "$ds" | jq -r '.session_file // empty' 2>/dev/null)"
+        if [[ -z "$ds_session_file" || -z "$ds_actor" || -z "$ds_addr" || -z "$ds_dkh" || -z "$ds_pop" ]]; then
           fail "P.1 install" "in-sandbox daemon redeem failed: $(echo "$ds" | tr '\n' ' ' | cut -c1-200)"
         elif [[ "$ds_actor" != "$child_omni" ]]; then
           fail "P.1 install" "redeemed omni ${ds_actor:0:14}… != created child ${child_omni:0:14}… (broker/derivation mismatch)"
         elif [[ -n "$prior_dkh" && "$ds_dkh" == "$prior_dkh" ]]; then
           fail "P.1 install" "fresh pairing produced the SAME device_key_hash as the prior run ($ds_dkh) — the P.depair K10 wipe did not take; this is NOT a genuine re-pair"
         else
-          ACTOR_OMNI="$ds_actor"; AGENT_SESSION_BEARER="$ds_jwt"; DEVICE_KEY_HASH="$ds_dkh"
+          ACTOR_OMNI="$ds_actor"; AGENT_SESSION_FILE="$ds_session_file"; DEVICE_KEY_HASH="$ds_dkh"
           # Record the (public) device hash in a sandbox sidecar so the NEXT fresh
           # run can depair THIS exact device (P.depair). It's the on-chain id, not
           # the key — custody is unaffected.
@@ -658,7 +663,16 @@ phase1_sandbox() {
     # worker's S3 ops are AWS-scoped to bots/<actor>/memory/. Without it the
     # worker falls back to its instance profile (no S3) and every op 502s.
     mcp_relayarg=""
-    [[ -n "$AGENT_SESSION_BEARER" ]] && mcp_relayarg="--agent-session-bearer $AGENT_SESSION_BEARER --memory-role-arn ${MEMORY_ROLE_ARN:-} --vault-role-arn ${VAULT_ROLE_ARN:-} --aws-region ${REGION:-us-east-1}"
+    # Fresh-pairing passes the bearer by FILE (sandbox path — finding 2: the JWT
+    # never transits the master/ps); --reuse-agent passes the value it minted on
+    # the master. Either configures the per-actor STS relay.
+    local mcp_session_arg=""
+    if [[ -n "$AGENT_SESSION_FILE" ]]; then
+      mcp_session_arg="--agent-session-bearer-file $AGENT_SESSION_FILE"
+    elif [[ -n "$AGENT_SESSION_BEARER" ]]; then
+      mcp_session_arg="--agent-session-bearer $AGENT_SESSION_BEARER"
+    fi
+    [[ -n "$mcp_session_arg" ]] && mcp_relayarg="$mcp_session_arg --memory-role-arn ${MEMORY_ROLE_ARN:-} --vault-role-arn ${VAULT_ROLE_ARN:-} --aws-region ${REGION:-us-east-1}"
     cmd="$MCP_BIN_DST --backend http --transport http --listen 127.0.0.1:$MCP_PORT --vendor-tokens $mcp_vendor --broker-url ${BROKER_URL:-} --memory-url ${AGENTKEYS_WORKER_MEMORY_URL:-} --audit-url ${AGENTKEYS_WORKER_AUDIT_URL:-} --default-actor $ACTOR_OMNI --default-operator-omni $OPERATOR_OMNI --default-device-key-hash $DEVICE_KEY_HASH $mcp_relayarg"
   fi
   # Reuse only if a live server's argv carries the intended backend + token AND
@@ -667,11 +681,12 @@ phase1_sandbox() {
   # light mode makes that last grep a no-op (empty pattern matches every line).
   # In real mode with the STS relay, never reuse: the agent session bearer is
   # freshly minted each run (0.8), and a reused server would hold a stale bearer
-  # → mint-oidc-jwt 401 on every memory op. -z "$AGENT_SESSION_BEARER" is true in
-  # light mode (and real-without-relay), preserving fast reuse there.
+  # → mint-oidc-jwt 401 on every memory op. -z both AGENT_SESSION_BEARER and
+  # AGENT_SESSION_FILE is true in light mode (and real-without-relay), preserving
+  # fast reuse there.
   local reuse=false
   if [[ "$mcp_bin_changed" != true \
-        && -z "$AGENT_SESSION_BEARER" \
+        && -z "$AGENT_SESSION_BEARER" && -z "$AGENT_SESSION_FILE" \
         && "$(sbx_rc "curl -fsS http://localhost:$MCP_PORT/healthz")" == "0" \
         && -n "$(sbx_exec "pgrep -af agentkeys-mcp-server | grep -F -- '--backend $mcp_backend' | grep -F -- '--vendor-tokens $mcp_vendor' | grep -F -- '$mcp_brokerarg'")" ]]; then
     reuse=true

From cc6dc02b067d198272d40f59acb8c237127c165e Mon Sep 17 00:00:00 2001
From: Hanwen Cheng <heawen.cheng@gmail.com>
Date: Mon, 1 Jun 2026 00:22:03 +0800
Subject: [PATCH 21/23] harness: fix P.2 false-FAIL (jq on stderr-mixed output)
 + 0x-prefix ACTOR_OMNI for cap-mint
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two issues surfaced on a full §10.2 fresh-pairing run:

P.2 false-FAIL (my finding-3 regression): the check ran 'jq -e' on $reg = heima-agent-create.sh 2>&1 (stderr logs + the JSON line). jq can't parse the mixed text → silently fails → P.2 reported FAIL even though registerAgentDevice SUCCEEDED (real tx 0x90f7…, block 9690030). Now extract the JSON line (grep -oE '{.*}' | tail -1) before jq.

cap-mint 400 'actor_omni must start with 0x' (1.5/3.1/4.2): the §10.2 child omni is un-prefixed by design (child_omni_hex), but cap-mint's validate_hex32 requires 0x (like OPERATOR_OMNI, which is already 0x). ACTOR_OMNI was set to the bare child omni → cap_mint rejected it. Now ACTOR_OMNI="0x${ds_actor#0x}" (exactly one 0x); ds_actor stays un-prefixed for the chain helpers + the child_omni== check.

Follow-up (not demo-blocking): a production agent whose session omni is un-prefixed hits the same cap-mint 400; the durable fix is cap-mint accepting un-prefixed omnis (validate_hex32 -> normalize_hex32) or the MCP normalizing the request. Tracked separately. Refs #149.
---
 harness/phase1-wire-demo.sh | 17 +++++++++++++----
 1 file changed, 13 insertions(+), 4 deletions(-)

diff --git a/harness/phase1-wire-demo.sh b/harness/phase1-wire-demo.sh
index 3cd5e1a9..e34098f8 100755
--- a/harness/phase1-wire-demo.sh
+++ b/harness/phase1-wire-demo.sh
@@ -594,7 +594,11 @@ phase1_sandbox() {
         elif [[ -n "$prior_dkh" && "$ds_dkh" == "$prior_dkh" ]]; then
           fail "P.1 install" "fresh pairing produced the SAME device_key_hash as the prior run ($ds_dkh) — the P.depair K10 wipe did not take; this is NOT a genuine re-pair"
         else
-          ACTOR_OMNI="$ds_actor"; AGENT_SESSION_FILE="$ds_session_file"; DEVICE_KEY_HASH="$ds_dkh"
+          # cap-mint (validate_hex32) requires 0x-prefixed omnis, like OPERATOR_OMNI.
+          # The §10.2 child omni is un-prefixed by design, so normalize to exactly
+          # one 0x for --default-actor (else memory.put → cap_mint 400 "actor_omni
+          # must start with 0x"). ds_actor stays un-prefixed for the chain helpers.
+          ACTOR_OMNI="0x${ds_actor#0x}"; AGENT_SESSION_FILE="$ds_session_file"; DEVICE_KEY_HASH="$ds_dkh"
           # Record the (public) device hash in a sandbox sidecar so the NEXT fresh
           # run can depair THIS exact device (P.depair). It's the on-chain id, not
           # the key — custody is unaffected.
@@ -615,10 +619,15 @@ phase1_sandbox() {
           local reg; reg="$(bash "$REPO_ROOT/scripts/heima-agent-create.sh" --label "$AGENT_LABEL" \
             --agent-address "$ds_addr" --actor-omni "$ds_actor" --device-key-hash "$ds_dkh" --pop-sig "$ds_pop" 2>&1)"
           echo "$reg" | sed 's/^/        /' >&2
-          if echo "$reg" | grep -qiE '"skipped"[[:space:]]*:[[:space:]]*"already-registered"'; then
+          # heima-agent-create.sh prints stderr logs + a final JSON line; $reg is
+          # BOTH (2>&1), so extract the JSON line before jq — jq on the mixed text
+          # silently fails and would false-FAIL a real registration. The JSON
+          # discriminates a real tx_hash from the already-registered skip.
+          local reg_json; reg_json="$(echo "$reg" | grep -oE '\{.*\}' | tail -1)"
+          if echo "$reg_json" | jq -e '.skipped=="already-registered"' >/dev/null 2>&1; then
             fail "P.2 bind" "registerAgentDevice was SKIPPED (already-registered) — P.depair/P.1 did NOT yield a fresh device, so the pairing path was NOT exercised (check P.depair revoke + sandbox wipe): $(echo "$reg" | tr '\n' ' ' | cut -c1-160)"
-          elif echo "$reg" | jq -e '.ok==true and ((.tx_hash // "") != "")' >/dev/null 2>&1; then
-            ok "P.2 bind" "on-chain registerAgentDevice — REAL tx $(echo "$reg" | jq -r '.tx_hash' 2>/dev/null | cut -c1-18)… (fresh K10 from P.depair)"
+          elif echo "$reg_json" | jq -e '.ok==true and ((.tx_hash // "") != "")' >/dev/null 2>&1; then
+            ok "P.2 bind" "on-chain registerAgentDevice — REAL tx $(echo "$reg_json" | jq -r '.tx_hash' 2>/dev/null | cut -c1-18)… (fresh K10 from P.depair)"
             # Ack the rendezvous: tell the broker the master bound this device so it
             # drops out of pending-bindings (self-cleaning → idempotent re-runs).
             curl -sS --max-time 15 -X POST "${BROKER_URL%/}/v1/agent/pending-bindings/ack" \

From d7a4c013fbfc4705187d9fe9aabeafb6d0c8ec05 Mon Sep 17 00:00:00 2001
From: Hanwen Cheng <heawen.cheng@gmail.com>
Date: Mon, 1 Jun 2026 00:43:54 +0800
Subject: [PATCH 22/23] =?UTF-8?q?security:=20address=202nd=20adversarial?=
 =?UTF-8?q?=20review=20=E2=80=94=20full=20oidc=20gate=20invariant,=20harde?=
 =?UTF-8?q?ned=20key=20writes,=20reuse=20bearer=20custody?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A [high] oidc agent gate (oidc.rs) only checked active+actor; now mirrors the FULL cap-mint invariant — device.operator_omni == session parent_omni AND actor_omni == omni_account AND roles & ROLE_CAP_MINT AND active. Without the operator+role checks, any other registered operator could bind (this device hash, this actor) and the agent would pass, bypassing the master that issued the link code. Exposed cap.rs DeviceEntry.operator_omni/roles + ROLE_CAP_MINT as pub(crate).

B [high] write_key_0600 (agentkeys-core/device_crypto.rs): mode(0o600) only applies on CREATE, so a pre-existing loose-perms file kept its mode, and open() followed symlinks. Now rejects a pre-existing symlink/non-regular target and force-chmods 0600 after open. Residual TOCTOU (needs O_NOFOLLOW/libc) noted as follow-up.

C [medium] harness --reuse-agent passed --agent-session-bearer <value> (in the MCP argv/ps); now stages the master-minted bearer into the same owner-only sandbox file (umask 077) and passes only --agent-session-bearer-file, matching fresh-pairing. Neither mode leaves the JWT in ps.

cargo test -p agentkeys-core green (141+3); broker+daemon+mcp build clean; bash -n harness clean. Refs #149.
---
 .../src/handlers/cap.rs                       |  6 ++---
 .../src/handlers/oidc.rs                      | 23 ++++++++++++++-----
 crates/agentkeys-core/src/device_crypto.rs    | 19 ++++++++++++++-
 harness/phase1-wire-demo.sh                   |  8 ++++++-
 4 files changed, 45 insertions(+), 11 deletions(-)

diff --git a/crates/agentkeys-broker-server/src/handlers/cap.rs b/crates/agentkeys-broker-server/src/handlers/cap.rs
index 297ce809..6209e012 100644
--- a/crates/agentkeys-broker-server/src/handlers/cap.rs
+++ b/crates/agentkeys-broker-server/src/handlers/cap.rs
@@ -320,7 +320,7 @@ async fn mint_cap(
 
 // ─── on-chain reads (raw eth_call over reqwest) ────────────────────────
 
-const ROLE_CAP_MINT: u8 = 1;
+pub(crate) const ROLE_CAP_MINT: u8 = 1;
 
 #[derive(Debug)]
 pub(crate) struct ChainContracts {
@@ -364,9 +364,9 @@ fn profile_env(profile_uc: &str, base: &str) -> Result<String, CapError> {
 
 #[derive(Debug)]
 pub(crate) struct DeviceEntry {
-    operator_omni: String, // hex without 0x
+    pub(crate) operator_omni: String, // hex without 0x
     pub(crate) actor_omni: String,
-    roles: u8,
+    pub(crate) roles: u8,
     pub(crate) registered_at: u64,
     pub(crate) revoked: bool,
 }
diff --git a/crates/agentkeys-broker-server/src/handlers/oidc.rs b/crates/agentkeys-broker-server/src/handlers/oidc.rs
index 83d27ee2..56871add 100644
--- a/crates/agentkeys-broker-server/src/handlers/oidc.rs
+++ b/crates/agentkeys-broker-server/src/handlers/oidc.rs
@@ -119,7 +119,13 @@ pub async fn mint_oidc_jwt(
     // Wallet/master sessions (no device_pubkey) are the operator's own and unaffected.
     // Same on-chain check the cap-mint path uses (SidecarRegistry.getDevice).
     if let Some(device_pubkey) = session_claims.agentkeys.device_pubkey.as_deref() {
-        use crate::handlers::cap::{call_get_device, ChainContracts};
+        use crate::handlers::cap::{call_get_device, ChainContracts, ROLE_CAP_MINT};
+        // Mirror the FULL cap-mint invariant (cap.rs verify_chain): the device must
+        // be active AND bound to BOTH the session's operator (parent_omni) and actor
+        // (omni_account), with the CAP_MINT role. Checking only actor would let any
+        // OTHER registered operator bind (this device hash, this actor) and pass the
+        // gate, bypassing the master that issued the link code.
+        let parent_omni = session_claims.agentkeys.parent_omni.as_deref().unwrap_or("");
         let chain = ChainContracts::from_state(&state)
             .map_err(|e| BrokerError::Internal(format!("chain config for agent gate: {e:?}")))?;
         let dkh = agentkeys_core::device_crypto::device_key_hash(device_pubkey)
@@ -127,12 +133,17 @@ pub async fn mint_oidc_jwt(
         let device = call_get_device(&state.http, &chain.rpc_url, &chain.registry, &dkh)
             .await
             .map_err(|e| BrokerError::Internal(format!("on-chain device read: {e:?}")))?;
-        let denied: Option<&str> = if device.registered_at == 0 || device.revoked {
+        let norm = |s: &str| s.trim_start_matches("0x").to_lowercase();
+        let denied: Option<&str> = if parent_omni.is_empty() {
+            Some("agent session missing parent_omni lineage — cannot verify operator binding")
+        } else if device.registered_at == 0 || device.revoked {
             Some("agent device not active on-chain — the master must registerAgentDevice (bind) before this agent can mint OIDC/STS credentials")
-        } else if device.actor_omni.to_lowercase()
-            != actor_omni.trim_start_matches("0x").to_lowercase()
-        {
-            Some("session omni does not match the on-chain device's actor_omni")
+        } else if norm(&device.operator_omni) != norm(parent_omni) {
+            Some("on-chain device operator_omni does not match the agent session's parent_omni")
+        } else if norm(&device.actor_omni) != norm(&actor_omni) {
+            Some("on-chain device actor_omni does not match the session omni")
+        } else if (device.roles & ROLE_CAP_MINT) == 0 {
+            Some("on-chain device lacks the CAP_MINT role")
         } else {
             None
         };
diff --git a/crates/agentkeys-core/src/device_crypto.rs b/crates/agentkeys-core/src/device_crypto.rs
index 81a2e0d0..c5990985 100644
--- a/crates/agentkeys-core/src/device_crypto.rs
+++ b/crates/agentkeys-core/src/device_crypto.rs
@@ -111,7 +111,21 @@ fn expand_home(p: &str) -> String {
 #[cfg(unix)]
 pub fn write_key_0600(path: &str, content: &str) -> Result<()> {
     use std::io::Write;
-    use std::os::unix::fs::OpenOptionsExt;
+    use std::os::unix::fs::{OpenOptionsExt, PermissionsExt};
+    // Custody hardening: `mode(0o600)` is honoured ONLY when the file is freshly
+    // created — a pre-existing group/world-readable file would be truncated +
+    // rewritten while KEEPING its loose perms, and a planted symlink at `path`
+    // would redirect the write outside the owner-only file. So reject an existing
+    // symlink / non-regular target, and force 0600 AFTER opening (covers the
+    // pre-existing-loose-file case). Residual TOCTOU between the check and open is
+    // not closed here — O_NOFOLLOW would, but needs a libc dep (follow-up).
+    if let Ok(meta) = std::fs::symlink_metadata(path) {
+        if meta.file_type().is_symlink() || !meta.file_type().is_file() {
+            return Err(anyhow!(
+                "refusing to write {path}: existing target is a symlink/special file (key-custody)"
+            ));
+        }
+    }
     let mut f = std::fs::OpenOptions::new()
         .write(true)
         .create(true)
@@ -119,6 +133,9 @@ pub fn write_key_0600(path: &str, content: &str) -> Result<()> {
         .mode(0o600)
         .open(path)
         .with_context(|| format!("open {path} (0600)"))?;
+    // Force owner-only even if the file pre-existed with looser permissions.
+    f.set_permissions(std::fs::Permissions::from_mode(0o600))
+        .with_context(|| format!("chmod 0600 {path}"))?;
     f.write_all(content.as_bytes())?;
     Ok(())
 }
diff --git a/harness/phase1-wire-demo.sh b/harness/phase1-wire-demo.sh
index e34098f8..6fac1cc7 100755
--- a/harness/phase1-wire-demo.sh
+++ b/harness/phase1-wire-demo.sh
@@ -679,7 +679,13 @@ phase1_sandbox() {
     if [[ -n "$AGENT_SESSION_FILE" ]]; then
       mcp_session_arg="--agent-session-bearer-file $AGENT_SESSION_FILE"
     elif [[ -n "$AGENT_SESSION_BEARER" ]]; then
-      mcp_session_arg="--agent-session-bearer $AGENT_SESSION_BEARER"
+      # --reuse-agent mints the bearer on the master; stage it into the SAME
+      # owner-only sandbox file (umask 077 → 0600) and pass only the path, so the
+      # JWT is never in the MCP argv / process list (Codex finding C). Both pairing
+      # modes now feed the MCP by file, not by value.
+      local reuse_sf="$SBX_HOME/.agentkeys/agent-session.jwt"
+      sbx_exec "umask 077; mkdir -p ~/.agentkeys && printf '%s' '$AGENT_SESSION_BEARER' > '$reuse_sf'" >/dev/null 2>&1 || true
+      mcp_session_arg="--agent-session-bearer-file $reuse_sf"
     fi
     [[ -n "$mcp_session_arg" ]] && mcp_relayarg="$mcp_session_arg --memory-role-arn ${MEMORY_ROLE_ARN:-} --vault-role-arn ${VAULT_ROLE_ARN:-} --aws-region ${REGION:-us-east-1}"
     cmd="$MCP_BIN_DST --backend http --transport http --listen 127.0.0.1:$MCP_PORT --vendor-tokens $mcp_vendor --broker-url ${BROKER_URL:-} --memory-url ${AGENTKEYS_WORKER_MEMORY_URL:-} --audit-url ${AGENTKEYS_WORKER_AUDIT_URL:-} --default-actor $ACTOR_OMNI --default-operator-omni $OPERATOR_OMNI --default-device-key-hash $DEVICE_KEY_HASH $mcp_relayarg"

From 55c8c7db0fabbbebe7c4c178b2d636547757f57c Mon Sep 17 00:00:00 2001
From: Hanwen Cheng <heawen.cheng@gmail.com>
Date: Mon, 1 Jun 2026 01:08:57 +0800
Subject: [PATCH 23/23] style: cargo fmt the finding-A oidc gate edit (fixes CI
 fmt gate)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The agent-gate edit in d7a4c01 wasn't rustfmt-clean → CI 'cargo fmt --all -- --check' failed at 23s (parent_omni method chain + dkh map_err block). Ran cargo fmt --all (only oidc.rs affected). Verified locally with the EXACT CI commands: fmt --all --check clean, 'clippy --workspace --all-targets -- -D warnings' exit 0, 'test --workspace --test-threads=1' exit 0. Refs #149.
---
 crates/agentkeys-broker-server/src/handlers/oidc.rs | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/crates/agentkeys-broker-server/src/handlers/oidc.rs b/crates/agentkeys-broker-server/src/handlers/oidc.rs
index 56871add..6f3b1ad0 100644
--- a/crates/agentkeys-broker-server/src/handlers/oidc.rs
+++ b/crates/agentkeys-broker-server/src/handlers/oidc.rs
@@ -125,11 +125,16 @@ pub async fn mint_oidc_jwt(
         // (omni_account), with the CAP_MINT role. Checking only actor would let any
         // OTHER registered operator bind (this device hash, this actor) and pass the
         // gate, bypassing the master that issued the link code.
-        let parent_omni = session_claims.agentkeys.parent_omni.as_deref().unwrap_or("");
+        let parent_omni = session_claims
+            .agentkeys
+            .parent_omni
+            .as_deref()
+            .unwrap_or("");
         let chain = ChainContracts::from_state(&state)
             .map_err(|e| BrokerError::Internal(format!("chain config for agent gate: {e:?}")))?;
-        let dkh = agentkeys_core::device_crypto::device_key_hash(device_pubkey)
-            .map_err(|e| BrokerError::BadRequest(format!("bad device_pubkey in session claim: {e}")))?;
+        let dkh = agentkeys_core::device_crypto::device_key_hash(device_pubkey).map_err(|e| {
+            BrokerError::BadRequest(format!("bad device_pubkey in session claim: {e}"))
+        })?;
         let device = call_get_device(&state.http, &chain.rpc_url, &chain.registry, &dkh)
             .await
             .map_err(|e| BrokerError::Internal(format!("on-chain device read: {e:?}")))?;