@embassys/ambassador 0.2.9 → 0.2.10

package/dist/windows-access-control.js

@@ -0,0 +1,161 @@
+import { execFile, execFileSync } from "node:child_process";
+import { win32 } from "node:path";
+const SYSTEM_SID = "S-1-5-18";
+const POWERSHELL_TIMEOUT_MS = 30_000;
+const WINDOWS_HELPER_ENVIRONMENT_NAMES = [
+    "SystemRoot",
+    "WINDIR",
+    "ComSpec",
+    "PATHEXT",
+    "PATH",
+    "TEMP",
+    "TMP",
+    "USERPROFILE",
+    "LOCALAPPDATA",
+    "APPDATA",
+    "PROGRAMDATA",
+];
+const WINDOWS_ACL_SCRIPT = `
+$ErrorActionPreference = 'Stop'
+if ($args.Count -ne 0) { exit 41 }
+$target = [Environment]::GetEnvironmentVariable('AMBASSADOR_ACL_PATH', 'Process')
+$kind = [Environment]::GetEnvironmentVariable('AMBASSADOR_ACL_KIND', 'Process')
+if ([String]::IsNullOrEmpty($target)) { exit 42 }
+$attributes = [System.IO.File]::GetAttributes($target)
+if (($attributes -band [System.IO.FileAttributes]::ReparsePoint) -ne 0) { exit 43 }
+$isDirectory = ($attributes -band [System.IO.FileAttributes]::Directory) -ne 0
+if (($kind -eq 'directory') -ne $isDirectory) { exit 44 }
+if ($kind -ne 'directory' -and $kind -ne 'file') { exit 45 }
+$userIdentity = [System.Security.Principal.WindowsIdentity]::GetCurrent().User
+$userSid = $userIdentity.Value
+$artifact = if ($isDirectory) {
+  [System.IO.DirectoryInfo]::new($target)
+} else {
+  [System.IO.FileInfo]::new($target)
+}
+$security = if ($isDirectory) {
+  [System.Security.AccessControl.DirectorySecurity]::new()
+} else {
+  [System.Security.AccessControl.FileSecurity]::new()
+}
+$security.SetOwner($userIdentity)
+$security.SetAccessRuleProtection($true, $false)
+$inheritance = if ($isDirectory) {
+  [System.Security.AccessControl.InheritanceFlags]'ContainerInherit,ObjectInherit'
+} else {
+  [System.Security.AccessControl.InheritanceFlags]::None
+}
+$expected = [System.Collections.Generic.HashSet[string]]::new(
+  [System.StringComparer]::OrdinalIgnoreCase
+)
+[void]$expected.Add($userSid)
+[void]$expected.Add('${SYSTEM_SID}')
+foreach ($sid in $expected) {
+  $identity = [System.Security.Principal.SecurityIdentifier]::new($sid)
+  $rule = [System.Security.AccessControl.FileSystemAccessRule]::new(
+    $identity,
+    [System.Security.AccessControl.FileSystemRights]::FullControl,
+    $inheritance,
+    [System.Security.AccessControl.PropagationFlags]::None,
+    [System.Security.AccessControl.AccessControlType]::Allow
+  )
+  [void]$security.AddAccessRule($rule)
+}
+$artifact.SetAccessControl($security)
+$actual = $artifact.GetAccessControl(
+  [System.Security.AccessControl.AccessControlSections]'Access,Owner'
+)
+if (-not $actual.AreAccessRulesProtected) { exit 46 }
+if ($actual.GetOwner([System.Security.Principal.SecurityIdentifier]).Value -ne $userSid) {
+  exit 47
+}
+$rules = @($actual.GetAccessRules(
+  $true,
+  $true,
+  [System.Security.Principal.SecurityIdentifier]
+))
+if ($rules.Count -ne $expected.Count) { exit 48 }
+foreach ($rule in $rules) {
+  if (-not $expected.Contains($rule.IdentityReference.Value)) { exit 49 }
+  if ($rule.IsInherited) { exit 50 }
+  if ($rule.AccessControlType -ne [System.Security.AccessControl.AccessControlType]::Allow) {
+    exit 51
+  }
+  if ([int]$rule.FileSystemRights -ne [int][System.Security.AccessControl.FileSystemRights]::FullControl) {
+    exit 52
+  }
+  if ($rule.InheritanceFlags -ne $inheritance) { exit 53 }
+  if ($rule.PropagationFlags -ne [System.Security.AccessControl.PropagationFlags]::None) {
+    exit 54
+  }
+}
+[Console]::Out.Write('AMBASSADOR_ACL_OK')
+`;
+function powershellExecutable() {
+    const systemRoot = process.env.SystemRoot;
+    if (systemRoot === undefined ||
+        !win32.isAbsolute(systemRoot) ||
+        systemRoot.includes("\u0000") ||
+        systemRoot.includes("\r") ||
+        systemRoot.includes("\n")) {
+        throw new Error("Windows state access control failed");
+    }
+    return win32.join(systemRoot, "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
+}
+function helperEnvironment(path, kind) {
+    if (path.length < 1 || path.length > 32_768 || path.includes("\u0000")) {
+        throw new Error("Windows state access control failed");
+    }
+    const environment = {};
+    for (const name of WINDOWS_HELPER_ENVIRONMENT_NAMES) {
+        const value = process.env[name];
+        if (value !== undefined)
+            environment[name] = value;
+    }
+    environment.AMBASSADOR_ACL_PATH = path;
+    environment.AMBASSADOR_ACL_KIND = kind;
+    return environment;
+}
+function arguments_() {
+    return [
+        "-NoLogo",
+        "-NoProfile",
+        "-NonInteractive",
+        "-EncodedCommand",
+        Buffer.from(WINDOWS_ACL_SCRIPT, "utf16le").toString("base64"),
+    ];
+}
+function options(path, kind) {
+    return {
+        encoding: "utf8",
+        env: helperEnvironment(path, kind),
+        maxBuffer: 32 * 1024,
+        timeout: POWERSHELL_TIMEOUT_MS,
+        windowsHide: true,
+    };
+}
+export async function secureWindowsArtifact(path, kind) {
+    const output = await new Promise((resolve, reject) => {
+        execFile(powershellExecutable(), arguments_(), options(path, kind), (error, stdout, stderr) => {
+            if (error !== null || stderr.length !== 0 || stdout !== "AMBASSADOR_ACL_OK") {
+                reject(new Error("Windows state access control failed"));
+                return;
+            }
+            resolve(stdout);
+        });
+    });
+    if (output !== "AMBASSADOR_ACL_OK")
+        throw new Error("Windows state access control failed");
+}
+export function secureWindowsArtifactSync(path, kind) {
+    let output;
+    try {
+        output = execFileSync(powershellExecutable(), arguments_(), options(path, kind));
+    }
+    catch {
+        throw new Error("Windows state access control failed");
+    }
+    if (output !== "AMBASSADOR_ACL_OK")
+        throw new Error("Windows state access control failed");
+}
+//# sourceMappingURL=windows-access-control.js.map

package/dist/windows-access-control.js.map

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

package/docs/development-reset.md

@@ -0,0 +1,27 @@
+# Reset local test state
+
+This removes only local Ambassador test residue. It does not call the central
+service or delete a registered central identity.
+
+1. Stop `ambassador start`.
+2. Delete the complete Ambassador state directory for the test account:
+
+   | Platform | Default state directory |
+   | --- | --- |
+   | macOS | `~/Library/Application Support/ambassador` |
+   | Linux | `${XDG_STATE_HOME:-~/.local/state}/ambassador` |
+   | Windows | `%LOCALAPPDATA%\ambassador` |
+
+   The directory contains the encrypted central credential and key, encrypted
+   webhook secret and key, delivery profile, ID-only notification journal, and
+   process lock. Delete the directory only after checking the exact path.
+
+3. Remove any test-only Ambassador MCP entry, Hermes webhook route, or
+   OpenClaw plugin configuration that you created for the run. Do not remove
+   normal provider credentials.
+4. Start Ambassador again from the working directory you want the new direct
+   profile to use.
+
+Because this is a local-only reset, central still owns the old email identity.
+Use a new disposable email when repeating registration. A `409` for the old
+address is expected and is not fixed by deleting local files.

package/docs/getting-started-claude.md

@@ -3,9 +3,9 @@
 ## Before you start
 
 - Install Node.js `>=24.19.0 <25`.
-- Install and authenticate the latest Claude Code release.
-- For direct delivery, install the latest
-  `@agentclientprotocol/claude-agent-acp` so `claude-agent-acp` is on `PATH`.
+- Install Claude Code.
+- For direct delivery, install `@agentclientprotocol/claude-agent-acp` so
+  `claude-agent-acp` is on `PATH`.
 - Sign in to Claude Code normally. Ambassador never receives your Claude
   credential.
 

package/docs/getting-started-codex.md

@@ -3,9 +3,9 @@
 ## Before you start
 
 - Install Node.js `>=24.19.0 <25`.
-- Install and authenticate the latest Codex release.
-- For direct delivery, install the latest `@agentclientprotocol/codex-acp` so
-  `codex-acp` is on `PATH`.
+- Install Codex.
+- For direct delivery, install `@agentclientprotocol/codex-acp` so `codex-acp`
+  is on `PATH`.
 - Sign in to Codex normally. Ambassador never receives your Codex credential.
 
 ## Set up direct delivery

package/docs/getting-started-gemini.md

@@ -3,7 +3,7 @@
 ## Before you start
 
 - Install Node.js `>=24.19.0 <25`.
-- Install and sign in to the latest Gemini CLI release.
+- Install and sign in to Gemini CLI.
 - Gemini supplies native ACP through `gemini --acp`; no adapter is needed.
 - Ambassador never receives your Gemini or Google credential.
 

package/docs/getting-started-hermes.md

@@ -3,49 +3,101 @@
 ## Before you start
 
 - Install Node.js `>=24.19.0 <25`.
-- Install and authenticate the latest Hermes Agent release.
+- Install and authenticate Hermes Agent.
 - Make sure `hermes-acp` is on `PATH` for direct delivery.
 - Ambassador never receives your provider credential.
 
 ## Set up direct delivery
 
-1. From the directory Hermes may access, keep Ambassador running:
+1. From the directory Hermes may access, keep the latest Ambassador running:
 
    ```sh
    npx --yes @embassys/ambassador@latest start
    ```
 
-2. Add `http://127.0.0.1:8787/mcp` as a Streamable HTTP MCP server in Hermes's
-   normal MCP configuration. Do not configure authentication.
+2. Add the endpoint printed by Ambassador as an unauthenticated Streamable
+   HTTP MCP server:
+
+   ```sh
+   hermes mcp add ambassador \
+     --url http://127.0.0.1:8787/mcp \
+     --connect-timeout 15
+   ```
+
+   Replace the URL if Ambassador printed a different loopback port. Do not
+   configure authentication.
 3. Start or restart Hermes so it sees the MCP server.
-4. Ask Hermes to register your email; it calls Ambassador's `register_agent`
+4. Ask Hermes to register your email. It calls Ambassador's `register_agent`
    tool.
 5. Choose **Send directly to this Hermes agent**.
 6. Enter the six-digit code sent to your email.
 
-Ambassador will launch `hermes-acp` when a central message arrives. That is a
-new gateway-managed session, not the chat used for registration.
+Ambassador launches `hermes-acp` when a central message arrives. That is a new
+gateway-managed session, not the chat used for registration. Reported versions
+are diagnostic only: Ambassador tries the fixed ACP v1 command and exact
+`hermes-agent` identity, then reports a bounded startup, initialization,
+session, or delivery failure if they are incompatible.
+
+## Set up webhook delivery
 
-## Use a webhook instead
+Hermes has a native generic webhook receiver. Configure one owner-controlled
+route that uses the same value for Ambassador's bearer and HMAC V2 contract:
+
+1. With Ambassador running, choose **Send to a webhook** during registration.
+   Ambassador responds with:
+
+   ```sh
+   npx --yes @embassys/ambassador@latest webhook-secret
+   ```
+
+   Ambassador creates the secret, encrypts it in its own owner-only state, and
+   displays it. Repeating the command displays the same value; it does not
+   rotate it.
+
+2. Enable Hermes webhooks with `WEBHOOK_ENABLED=true` and your chosen
+   `WEBHOOK_PORT` in Hermes's owner-only `.hermes/.env`. Add this route to
+   `.hermes/webhook_subscriptions.json`, replacing both placeholders with the
+   displayed value and preserving any existing routes:
+
+   ```json
+   {
+     "embassys": {
+       "description": "Embassys Ambassador",
+       "events": [],
+       "filters": [
+         {
+           "field": "headers.Authorization",
+           "equals": "Bearer PASTE_AMBASSADOR_SECRET_HERE"
+         }
+       ],
+       "prompt": "",
+       "skills": [],
+       "deliver": "log",
+       "secret": "PASTE_AMBASSADOR_SECRET_HERE"
+     }
+   }
+   ```
+
+   Keep the file mode `0600`. An empty prompt passes the complete canonical
+   JSON to the model. The route uses Hermes's normal tool configuration, so
+   keep the Ambassador MCP server enabled there.
+
+3. Start or restart `hermes gateway run`. The local receiver URL is normally:
+
+   ```text
+   http://127.0.0.1:8644/webhooks/embassys
+   ```
 
-- Before step 1, set the receiver secret in the same shell:
+   Use the actual configured port. A non-loopback receiver must use an HTTPS
+   URL.
 
-  ```sh
-  export AMBASSADOR_WEBHOOK_SECRET="$(
-    node -e "process.stdout.write(require('node:crypto').randomBytes(24).toString('hex'))"
-  )"
-  ```
+4. Retry `register_agent` with webhook selected and that URL. MCP carries only
+   `delivery.mode` and `delivery.url`; it never carries the secret or a secret
+   name.
 
-- During registration, choose **Send to a webhook**.
-- Give Hermes the HTTPS webhook URL and the variable name
-  `AMBASSADOR_WEBHOOK_SECRET`.
-- Hermes supplies `delivery.url` and `delivery.secret_env`; it never receives
-  the secret value.
+Hermes validates the bearer filter and HMAC V2 timestamp/signature before its
+model runs. A webhook `2xx` proves custody only. Keep both Hermes and
+Ambassador running until the model calls `respond_to_permission` or
+`submit_action_result` and the requester receives the correlated response.
 
-Ambassador selects this profile by the exact known MCP client name, then tries
-the fixed `hermes-acp` ACP v1 contract for direct delivery. Reported client and
-agent versions are diagnostic only. An incompatible release fails at startup,
-ACP initialization, session creation, or delivery instead of being rejected by
-a version list. See
-[Qualification](qualification.md) for the artifact-specific compatibility
-evidence.
+For local reruns, see [Reset local test state](development-reset.md).

package/docs/getting-started-openclaw.md

@@ -3,49 +3,110 @@
 ## Before you start
 
 - Install Node.js `>=24.19.0 <25`.
-- Install and authenticate the latest OpenClaw release.
+- Install and authenticate OpenClaw.
 - Make sure `openclaw` is on `PATH` for direct delivery.
 - Ambassador never receives your provider credential.
 
 ## Set up direct delivery
 
-1. From the directory OpenClaw may access, keep Ambassador running:
+1. From the directory OpenClaw may access, keep the latest Ambassador running:
 
    ```sh
    npx --yes @embassys/ambassador@latest start
    ```
 
-2. Add `http://127.0.0.1:8787/mcp` as a Streamable HTTP MCP server in
-   OpenClaw's normal MCP configuration. Do not configure authentication.
+2. Add the endpoint printed by Ambassador as an unauthenticated Streamable
+   HTTP MCP server, then probe it:
+
+   ```sh
+   openclaw mcp set ambassador \
+     '{"url":"http://127.0.0.1:8787/mcp","transport":"streamable-http","enabled":true}'
+   openclaw mcp doctor ambassador --probe
+   ```
+
+   Replace the URL if Ambassador printed a different loopback port. Do not
+   configure authentication.
 3. Start or restart OpenClaw so it sees the MCP server.
-4. Ask OpenClaw to register your email; it calls Ambassador's `register_agent`
-   tool.
+4. Ask OpenClaw to register your email. It calls Ambassador's
+   `register_agent` tool.
 5. Choose **Send directly to this OpenClaw agent**.
 6. Enter the six-digit code sent to your email.
 
-Ambassador will launch `openclaw acp` when a central message arrives. OpenClaw
+Ambassador launches `openclaw acp` when a central message arrives. OpenClaw
 does not accept session MCP injection, so keep the provider-side MCP entry from
-step 2 configured.
-
-## Use a webhook instead
-
-- Before step 1, set the receiver secret in the same shell:
-
-  ```sh
-  export AMBASSADOR_WEBHOOK_SECRET="$(
-    node -e "process.stdout.write(require('node:crypto').randomBytes(24).toString('hex'))"
-  )"
-  ```
-
-- During registration, choose **Send to a webhook**.
-- Give OpenClaw the HTTPS webhook URL and the variable name
-  `AMBASSADOR_WEBHOOK_SECRET`.
-- OpenClaw supplies `delivery.url` and `delivery.secret_env`; it never receives
-  the secret value.
-
-Ambassador selects this profile by the exact known MCP client name, then tries
-the fixed `openclaw acp` ACP v1 contract for direct delivery. Reported client
-and agent versions are diagnostic only. An incompatible release fails at
-startup, ACP initialization, session creation, or delivery instead of being
-rejected by a version list. See
-[Qualification](qualification.md) for compatibility evidence.
+step 2 configured. Reported versions are diagnostic only: Ambassador tries the
+fixed ACP v1 command and exact `openclaw-acp` identity, then reports a bounded
+startup, initialization, session, or delivery failure if they are incompatible.
+
+## Set up webhook delivery
+
+Webhook mode needs the receiver plugin shipped inside the latest Ambassador
+package. Install Ambassador and the plugin once:
+
+```sh
+npm install --global @embassys/ambassador@latest
+openclaw plugins install --accept-capabilities \
+  "$(npm root --global)/@embassys/ambassador/integrations/openclaw-ambassador"
+```
+
+The capability is an exact authenticated HTTP route. Review and accept it only
+from the Ambassador package you installed.
+
+1. With `ambassador start` still running, choose **Send to a webhook** during
+   registration. Ambassador responds with this setup command:
+
+   ```sh
+   ambassador webhook-secret
+   ```
+
+   Ambassador creates the secret, encrypts it in its own owner-only state, and
+   displays it. Repeating the command displays the same value; it does not
+   rotate it.
+
+2. Store the displayed value in OpenClaw without putting it in shell history:
+
+   ```sh
+   openclaw secrets store set AMBASSADOR_WEBHOOK_SECRET --value-file -
+   ```
+
+   Paste the value, press Enter, then send end-of-file (`Ctrl-D`). Point the
+   plugin at that store entry:
+
+   ```sh
+   openclaw config set plugins.entries.embassys-ambassador.config.secret \
+     --ref-source store --ref-provider default \
+     --ref-id AMBASSADOR_WEBHOOK_SECRET
+   openclaw plugins enable embassys-ambassador --accept-capabilities
+   ```
+
+   The plugin starts the configured OpenClaw agent, which defaults to `main`.
+   It does not select a model or expose the webhook secret to the model.
+
+3. Restart the OpenClaw gateway and run `openclaw plugins doctor`. The local
+   receiver URL is normally:
+
+   ```text
+   http://127.0.0.1:18789/embassys/ambassador
+   ```
+
+   Use the actual configured gateway port. A non-loopback receiver must use an
+   HTTPS URL.
+
+4. Retry `register_agent` with webhook selected and that URL. MCP carries only
+   `delivery.mode` and `delivery.url`; it never carries the secret or a secret
+   name.
+
+The plugin verifies Ambassador's bearer token, exact-body HMAC V2 signature,
+five-minute timestamp window, request ID, and idempotency key before placing the
+message on a bounded in-memory service queue. That service starts the normal
+OpenClaw model turn outside the completed HTTP request. A webhook `202` proves
+that OpenClaw accepted custody. It does not by itself prove that the model later
+called Ambassador MCP; end-to-end checks must wait for the correlated
+permission or action response.
+
+If OpenClaw reports `model execution failed`, run `openclaw plugins doctor` and
+check that the agent's own provider credential and Ambassador MCP entry are
+available to the OpenClaw gateway. Ambassador intentionally logs only a safe
+failure category, not the provider error or message body.
+
+For local reruns, see [Reset local test state](development-reset.md).

package/docs/live-qualification.md

@@ -11,7 +11,7 @@ general reply operations. It does test the deployed, action-specific
 The runner covers the current package name, guided registration, one
 full-message webhook target, and one direct target. The default direct target
 is the deterministic mock ACP agent. Separately confirmed modes use the fixed
-Codex or Hermes profiles. Real-provider modes use isolated provider
+Codex, Hermes, or OpenClaw profiles. Real-provider modes use isolated provider
 configuration copies. Installed-version probes are observational; production
 requires the exact known client and ACP agent names and then tries the fixed
 ACP v1 contract.
@@ -33,7 +33,8 @@ ACP v1 contract.
    direct profile. Prove a dual-mode profile advertises direct as its default;
    prove a direct-only profile proceeds without a delivery question.
 4. Receive and use both verification emails without persisting their codes.
-5. Restart and prove encrypted credential and nonsecret profile loading.
+5. Restart and prove encrypted credential, encrypted webhook-secret, and
+   nonsecret profile loading.
 6. Prove valid Bearer plus DPoP requests and the negative DPoP matrix.
 7. Validate the live action catalog against the recorded fixture schemas.
 8. Request and decide one synthetic `get_phone_number` permission.
@@ -113,6 +114,37 @@ mode starts Hermes's authenticated generic route,
 requires its bearer filter and native HMAC V2 validation, and suppresses
 provider output. Delete the isolated home after every attempt.
 
+For OpenClaw, prepare an owner-only temporary home containing copies of
+`.openclaw/openclaw.json`, `.openclaw/state/openclaw.sqlite`, and
+`.openclaw/agents/main/agent/openclaw-agent.sqlite`. Copy only the provider
+credential used by that OpenClaw agent; for the tested Codex-backed agent this
+also means `.codex/auth.json` and its provider configuration. Use SQLite's
+backup operation for live database copies. Put the installed `openclaw` on
+`PATH`, then choose one fixed mode:
+
+```sh
+export AMBASSADOR_OPENCLAW_QUALIFICATION_HOME=/absolute/path/to/isolated/home
+export AMBASSADOR_LIVE_DIRECT_AGENT=openclaw-direct
+export AMBASSADOR_CONFIRM_LIVE_QUALIFICATION=run-live-qualification-with-real-openclaw-direct-and-two-disposable-mailosaur-identities
+pnpm run qualify:live
+```
+
+or:
+
+```sh
+export AMBASSADOR_OPENCLAW_QUALIFICATION_HOME=/absolute/path/to/isolated/home
+export AMBASSADOR_LIVE_DIRECT_AGENT=openclaw-webhook
+export AMBASSADOR_CONFIRM_LIVE_QUALIFICATION=run-live-qualification-with-real-openclaw-webhook-and-two-disposable-mailosaur-identities
+pnpm run qualify:live
+```
+
+The runner rejects the ordinary OpenClaw home. It configures Ambassador MCP
+only in the copy. Direct mode launches the fixed `openclaw acp` profile and
+requires ACP v1 plus exact agent name `openclaw-acp`. Webhook mode installs the
+package-shipped receiver into the copy, creates the secret through the packed
+Ambassador CLI, stores it through OpenClaw's secret store, and runs the real
+OpenClaw gateway. Delete the isolated home after every attempt.
+
 ## Required report
 
 Record only:
@@ -264,6 +296,45 @@ These observations approve the source registry's exact Hermes ACP 0.20.5
 entry. They do not show that published Ambassador 0.2.7 supports Hermes 0.20.5
 direct mode. Ambassador 0.2.8 contains the candidate change.
 
+## OpenClaw observations
+
+On 2026-09-03, authenticated OpenClaw 2026.8.2 ran on macOS arm64 with Node
+24.19.0 and passed the complete live correlated-result flow in direct and
+webhook modes with the Ambassador 0.2.10 candidate. Both modes registered and
+verified two disposable identities, reloaded encrypted Ambassador state after
+restart, exercised live REST and DPoP plus the deployed action catalog, and
+completed the synthetic phone-number permission and action round trip. The
+real OpenClaw model called `respond_to_permission` and called
+`submit_action_result` exactly once. The controlled requester received the
+correlated final response, and local completion or webhook custody preceded
+central acknowledgement. Final candidate digests and the separate mode results
+are recorded in [Delivery qualification](qualification.md).
+
+Direct mode proved ACP v1 initialization through fixed `openclaw acp`, exact
+agent name `openclaw-acp`, provider-side Ambassador MCP configuration, real
+model execution, and correlated submission. An earlier isolation attempt
+omitted the credential for the agent's configured provider backend; OpenClaw
+then ended the model turn with an authentication failure before any Ambassador
+MCP call. Adding that owner-only credential to the isolated copy made the
+unchanged direct flow pass. This was an isolation-fixture failure, not an
+Ambassador ACP incompatibility.
+
+Webhook mode proved the package-shipped route's bearer and exact-body HMAC V2
+checks, bounded custody queue, real model execution, Ambassador MCP calls, and
+the final response. Earlier receiver attempts returned `202` and Ambassador
+correctly acknowledged central, but OpenClaw made no model or MCP call. The
+first implementation omitted required embedded-run fields. After those were
+added, the detached run inherited the HTTP handler's released work-admission
+lease and OpenClaw rejected it with the safe class `GatewayDrainingError`. A
+plugin-service queue created outside the request context removes that false
+drain path. A `202` still proves custody only; the passing run waited for the
+model calls and requester response.
+
+All OpenClaw attempts used an owner-only isolated home. Mailosaur messages,
+temporary Ambassador state, the OpenClaw copy, and copied provider credentials
+were removed after qualification. No provider output or message content was
+recorded.
+
 ## Earlier direct observation
 
 On 2026-09-02, real Codex had already passed delivery, injected Ambassador MCP