delegation-layer 0.1.1

package/README.md

@@ -0,0 +1,221 @@
+# Delegation Layer
+
+Delegation Layer runs one bounded turn of a supported AI command line tool as a
+durable, supervised local task. It records the request before submission,
+checks the executable and its capabilities at runtime, and publishes a
+validated result that can be collected later.
+
+> **Preview release**
+>
+> The project publishes checksum-verified CLI releases and an npm package with
+> installers for the CLI and integration skill. The provider CLI and Pueue
+> remain host prerequisites.
+
+## What it does
+
+The `delegate` command accepts a finite brief, a canonical workspace, a
+permission mode, and a wall clock budget. It prepares a provider-specific
+launch profile, submits exactly one provider turn through Pueue, and stores
+immutable task records and output descriptors under a private state root.
+
+The companion `delegate-run` executable is started by the supervisor. It
+reconstructs the recorded profile, verifies that admission and launch still
+refer to the same executable, policy, workspace, and request, then captures and
+seals the provider result. A later `collect` call can recover a committed
+outcome without launching the provider again.
+
+## Requirements
+
+- Go 1.27.1 is needed only for source builds and the Homebrew formula.
+- Pueue 4.0.4 and a running `pueued` daemon using a private configuration.
+- A signed-in installation of one or more supported provider CLIs: `agy`,
+  `codex`, `claude`, `pi`, or `opencode`.
+- A Darwin or Linux host on amd64 or arm64 for the supplied build targets.
+  Provider availability is profile-specific; see the provider guide for native
+  platform prerequisites.
+- Node.js 18 or newer is needed for the npm and pnpm installers; Bun is needed
+  for the Bun installer.
+
+The provider executable must be available to the process that dispatches the
+task. Delegation Layer runs the provider's version and help commands before
+admission and accepts any reported version that is valid and advertises every
+flag required by the adapter. It does not pin a provider release or predeclared
+binary hash. A valid version here means nonempty trimmed UTF-8 output without control
+characters; it is not required to match a semantic-version pattern. The
+observed version is diagnostic evidence, while capability flags, executable
+identity, and provider behavior decide compatibility. No web release lookup or
+semver allowlist is used.
+
+## Install
+
+### Install the CLI
+
+The shell installer downloads the latest published release, verifies its
+checksum, and installs both `delegate` and `delegate-run` in
+`$HOME/.local/bin`:
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/hishamkaram/delegation-layer/main/install.sh | sh
+```
+
+Set `DELEGATION_LAYER_INSTALL_DIR` if you want to install somewhere other than
+`$HOME/.local/bin`.
+
+Homebrew installs the same two executables:
+
+```sh
+brew install hishamkaram/tap/delegation-layer
+```
+
+The npm package also provides a checksum-verified CLI installer through npm,
+pnpm, and Bun:
+
+```sh
+npx --yes delegation-layer install-cli
+pnpm dlx delegation-layer install-cli
+bunx --bun delegation-layer install-cli
+```
+
+For a source build, install both Go commands from the latest version:
+
+```sh
+go install github.com/hishamkaram/delegation-layer/cmd/delegate@latest
+go install github.com/hishamkaram/delegation-layer/cmd/delegate-run@latest
+```
+
+Ensure the directory used by the installer or Go is on `PATH`.
+
+Confirm the installation:
+
+```sh
+delegate --help
+delegate providers --json
+```
+
+### Install the agent integration skill
+
+The provider-agnostic skill is separate from the CLI installation. Hermes can
+install the current skill directly:
+
+```sh
+hermes skills install \
+  https://raw.githubusercontent.com/hishamkaram/delegation-layer/main/skills/agent-integration/SKILL.md
+```
+
+Any harness with a writable skill directory can use the dependency-free npm,
+pnpm, or Bun installer:
+
+```sh
+npx --yes delegation-layer \
+  --target "$HOME/.hermes/skills/agent-integration"
+pnpm dlx delegation-layer \
+  --target "$HOME/.hermes/skills/agent-integration"
+bunx --bun delegation-layer \
+  --target "$HOME/.hermes/skills/agent-integration"
+```
+
+The default package command copies only `SKILL.md` into the target directory.
+The package's explicit `install-cli` command installs the CLI separately; it
+does not change the skill or configure Pueue or a provider CLI. Release tags
+and `DELEGATION_LAYER_VERSION` remain available when a deployment needs a
+reproducible version.
+
+## Quick start
+
+Create a brief and a workspace outside the state root. Use an absolute path to
+the Pueue configuration that controls the private daemon:
+
+```sh
+mkdir -p "$HOME/delegation-workspace"
+printf '%s\n' 'Inspect the repository and summarize the current build status.' > brief.txt
+
+delegate --pueue-config /absolute/path/to/pueue.yml dispatch \
+  --provider codex:exec \
+  --brief "$PWD/brief.txt" \
+  --cwd "$HOME/delegation-workspace" \
+  --permission read-only \
+  --budget 30m \
+  --json
+```
+
+The response contains a task ID and separate admission, liveness, and
+publication fields. Observe it with `status`, wait for a terminal publication,
+then read the validated result with `collect`:
+
+```sh
+delegate status TASK_ID --json
+delegate collect TASK_ID --watch 5s --json
+```
+
+Use the exact task ID printed by `dispatch`. A continuation is a new task that
+names its predecessor with `--resume-task`; it never silently reuses the most
+recent conversation.
+
+## Providers
+
+| Profile | Modes | Options |
+| --- | --- | --- |
+| `antigravity:print` | `workspace-write` | `continuation`, `native-timeout` |
+| `codex:exec` | `read-only`, `workspace-write` | `continuation` |
+| `claude:print` | `read-only`, `workspace-write` | `continuation` |
+| `pi:json` | `read-only` | `continuation`, `model`, `effort` |
+| `opencode:run` | `read-only`, `workspace-write` | `continuation`, `model`, `effort` |
+
+Run `delegate providers --json` for the compiled capability catalog. See
+[providers](docs/providers.md) for launch behavior, policy boundaries, and
+runtime compatibility checks.
+Use `delegate capabilities --provider PROFILE --json` for one provider's
+provider-neutral contract. Its catalog response is descriptive; dispatch is
+where the supervised runtime probe establishes host compatibility.
+
+When native logins are available, `make acceptance-native` runs the Pi and
+OpenCode live gates through a private supervisor. A pass exits `0`; an
+unavailable executable, supervisor, or login emits a sanitized `BLOCKED`
+receipt and exits `2`, which the aggregate target treats as neutral. Real
+behavior and evidence failures still fail the target.
+
+The catalog uses public request option names. The public `effort` option maps
+to Pi's native `--thinking` flag and OpenCode's native `--variant` flag.
+
+## Safety model
+
+- Every task has one immutable request and one provider turn.
+- State, workspace, provider runtime, and temporary directories are canonical
+  and kept disjoint where the selected policy requires it.
+- The supervisor owns process lifetime; the runner owns capture and sealing.
+- Admission and launch re-check executable identity, effective policy, and
+  session identity.
+- Briefs and control responses are bounded. Sealed payloads and raw streams are
+  described by validated paths, sizes, and SHA-256 digests.
+- Provider authentication remains native to the provider CLI. Delegation Layer
+  does not copy credentials into task state or rewrite account settings.
+
+Read [security](docs/security.md) for the full boundary and its operational
+limitations.
+
+## Documentation
+
+- [Getting started](docs/getting-started.md) — install, configure, and run a
+  first task.
+- [CLI reference](docs/cli-reference.md) — commands, flags, responses, and
+  exit codes.
+- [Integration API](docs/api.md) — JSON responses, state semantics, and
+  idempotent client behavior.
+- [Provider guide](docs/providers.md) — supported profiles and compatibility
+  behavior.
+- [Architecture](docs/architecture.md) — task lifecycle and ownership.
+- [System components](diagrams/components.html) — current Archify component map.
+- [Task lifecycle](diagrams/lead-interface.html) — current Archify sequence view.
+- [Security](docs/security.md) — isolation, policy, and result integrity.
+- [Troubleshooting](docs/troubleshooting.md) — common setup and runtime
+  failures.
+- [Contributing](docs/contributing.md) — development setup and adapter
+  extension guidance.
+- [Agent integration skill](skills/agent-integration/SKILL.md) — provider-neutral
+  JSON and evidence handling guidance for agents.
+
+## License
+
+No public license has been declared yet. Treat the source and release artifacts
+as proprietary and do not redistribute them without the project owner's
+permission.

package/install.sh

@@ -0,0 +1,77 @@
+#!/usr/bin/env sh
+set -eu
+
+REPOSITORY="hishamkaram/delegation-layer"
+REQUESTED_VERSION="${DELEGATION_LAYER_VERSION:-latest}"
+INSTALL_DIR="${DELEGATION_LAYER_INSTALL_DIR:-$HOME/.local/bin}"
+
+fail() {
+  printf 'delegation-layer: %s\n' "$1" >&2
+  exit 1
+}
+
+for command_name in awk curl grep install mktemp tar uname; do
+  command -v "$command_name" >/dev/null 2>&1 || fail "required command not found: $command_name"
+done
+
+if [ "$REQUESTED_VERSION" = "latest" ]; then
+  latest_url="https://github.com/${REPOSITORY}/releases/latest"
+  resolved_url="$(curl -fsSL -o /dev/null -w '%{url_effective}' "$latest_url")" || fail "could not resolve the latest release"
+  VERSION="${resolved_url##*/}"
+else
+  VERSION="$REQUESTED_VERSION"
+  case "$VERSION" in
+    v*) ;;
+    *) VERSION="v${VERSION}" ;;
+  esac
+fi
+
+printf '%s\n' "$VERSION" | grep -Eq '^v[0-9]+\.[0-9]+\.[0-9]+$' || \
+  fail "invalid version: $VERSION"
+
+case "$(uname -s)" in
+  Linux) OS=Linux ;;
+  Darwin) OS=Darwin ;;
+  *) fail "unsupported operating system: $(uname -s)" ;;
+esac
+
+case "$(uname -m)" in
+  x86_64|amd64) ARCH=amd64 ;;
+  arm64|aarch64) ARCH=arm64 ;;
+  *) fail "unsupported architecture: $(uname -m)" ;;
+esac
+
+ARCHIVE="delegation-layer_${VERSION#v}_${OS}_${ARCH}.tar.gz"
+RELEASE_URL="https://github.com/${REPOSITORY}/releases/download/${VERSION}"
+TEMP_DIR="$(mktemp -d)"
+trap 'rm -rf "$TEMP_DIR"' EXIT
+
+curl -fsSL --retry 3 -o "$TEMP_DIR/$ARCHIVE" "$RELEASE_URL/$ARCHIVE" || \
+  fail "could not download $ARCHIVE"
+curl -fsSL --retry 3 -o "$TEMP_DIR/checksums.txt" "$RELEASE_URL/checksums.txt" || \
+  fail "could not download checksums.txt"
+
+CHECKSUM_LINE="$(awk -v archive="$ARCHIVE" '$2 == archive { print; exit }' "$TEMP_DIR/checksums.txt")"
+[ -n "$CHECKSUM_LINE" ] || fail "checksums.txt does not contain $ARCHIVE"
+
+cd "$TEMP_DIR"
+if command -v sha256sum >/dev/null 2>&1; then
+  printf '%s\n' "$CHECKSUM_LINE" | sha256sum -c - || fail "checksum verification failed"
+elif command -v shasum >/dev/null 2>&1; then
+  printf '%s\n' "$CHECKSUM_LINE" | shasum -a 256 -c - || fail "checksum verification failed"
+else
+  fail "sha256sum or shasum is required for checksum verification"
+fi
+
+tar -xzf "$ARCHIVE" -C "$TEMP_DIR" || fail "could not extract $ARCHIVE"
+mkdir -p "$INSTALL_DIR"
+for binary in delegate delegate-run; do
+  [ -f "$TEMP_DIR/$binary" ] || fail "release archive does not contain $binary"
+  install -m 0755 "$TEMP_DIR/$binary" "$INSTALL_DIR/$binary"
+done
+
+printf 'Installed delegate and delegate-run %s in %s\n' "$VERSION" "$INSTALL_DIR"
+case ":${PATH:-}:" in
+  *:"$INSTALL_DIR":*) ;;
+  *) printf 'Add %s to PATH if it is not already there.\n' "$INSTALL_DIR" ;;
+esac

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "delegation-layer",
+  "version": "0.1.1",
+  "description": "Delegation Layer CLI and provider-agnostic agent skill installers.",
+  "type": "module",
+  "bin": {
+    "delegation-layer": "scripts/install-agent-integration.mjs"
+  },
+  "files": [
+    "install.sh",
+    "skills/agent-integration/SKILL.md",
+    "scripts/install-agent-integration.mjs",
+    "scripts/install-cli.mjs"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hishamkaram/delegation-layer.git"
+  },
+  "homepage": "https://github.com/hishamkaram/delegation-layer",
+  "bugs": {
+    "url": "https://github.com/hishamkaram/delegation-layer/issues"
+  },
+  "license": "UNLICENSED"
+}

package/scripts/install-agent-integration.mjs

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+
+import { copyFile, lstat, mkdir, readFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const sourcePath = join(packageRoot, "skills", "agent-integration", "SKILL.md");
+
+function usage(message) {
+  if (message) {
+    console.error(`Error: ${message}`);
+  }
+  console.error(
+    "Usage:\n  delegation-layer --target ABSOLUTE_SKILL_DIR [--force]\n  delegation-layer install-cli [--version VERSION] [--install-dir ABSOLUTE_DIR]",
+  );
+  process.exitCode = 2;
+}
+
+function parseArguments(argumentsList) {
+  let target;
+  let force = false;
+
+  for (let index = 0; index < argumentsList.length; index += 1) {
+    const argument = argumentsList[index];
+    if (argument === "--force") {
+      force = true;
+      continue;
+    }
+    if (argument === "--target") {
+      target = argumentsList[index + 1];
+      index += 1;
+      continue;
+    }
+    if (argument === "--help" || argument === "-h") {
+      console.log(
+        "Usage:\n  delegation-layer --target ABSOLUTE_SKILL_DIR [--force]\n  delegation-layer install-cli [--version VERSION] [--install-dir ABSOLUTE_DIR]",
+      );
+      process.exit(0);
+    }
+    usage(`unknown argument ${argument}`);
+    return null;
+  }
+
+  if (!target) {
+    usage("--target is required");
+    return null;
+  }
+  if (!isAbsolute(target)) {
+    usage("--target must be an absolute path");
+    return null;
+  }
+  return { force, target: resolve(target) };
+}
+
+async function existingPath(path) {
+  try {
+    return await lstat(path);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return null;
+    }
+    throw error;
+  }
+}
+
+async function install({ force, target }) {
+  const targetStat = await existingPath(target);
+  if (targetStat?.isSymbolicLink()) {
+    throw new Error(`target directory must not be a symlink: ${target}`);
+  }
+  if (targetStat && !targetStat.isDirectory()) {
+    throw new Error(`target must be a directory: ${target}`);
+  }
+
+  await mkdir(target, { recursive: true });
+
+  const destination = join(target, "SKILL.md");
+  const destinationStat = await existingPath(destination);
+  if (destinationStat?.isSymbolicLink()) {
+    throw new Error(`existing SKILL.md must not be a symlink: ${destination}`);
+  }
+  if (destinationStat && !destinationStat.isFile()) {
+    throw new Error(`existing SKILL.md is not a regular file: ${destination}`);
+  }
+
+  if (destinationStat && !force) {
+    const [source, existing] = await Promise.all([
+      readFile(sourcePath),
+      readFile(destination),
+    ]);
+    if (source.equals(existing)) {
+      console.log(`Skill already installed: ${destination}`);
+      return;
+    }
+    throw new Error(`SKILL.md already exists; use --force to replace it: ${destination}`);
+  }
+
+  await copyFile(sourcePath, destination);
+  console.log(`Installed agent integration skill: ${destination}`);
+}
+
+const argumentsList = process.argv.slice(2);
+if (argumentsList[0] === "install-cli") {
+  try {
+    const { main } = await import("./install-cli.mjs");
+    await main(argumentsList.slice(1));
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    process.exitCode = 1;
+  }
+} else {
+  const options = parseArguments(argumentsList);
+  if (options) {
+    try {
+      await install(options);
+    } catch (error) {
+      console.error(`Error: ${error.message}`);
+      process.exitCode = 1;
+    }
+  }
+}

package/scripts/install-cli.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+
+import { spawn } from "node:child_process";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const installerPath = join(packageRoot, "install.sh");
+
+function usage(message) {
+  if (message) {
+    console.error(`Error: ${message}`);
+  }
+  console.error(
+    "Usage: delegation-layer install-cli [--version VERSION] [--install-dir ABSOLUTE_DIR]",
+  );
+}
+
+function parseArguments(argumentsList) {
+  let version;
+  let installDir;
+
+  for (let index = 0; index < argumentsList.length; index += 1) {
+    const argument = argumentsList[index];
+    if (argument === "--version") {
+      version = argumentsList[index + 1];
+      index += 1;
+      if (!version) {
+        throw new Error("--version requires a value");
+      }
+      continue;
+    }
+    if (argument === "--install-dir") {
+      installDir = argumentsList[index + 1];
+      index += 1;
+      if (!installDir) {
+        throw new Error("--install-dir requires a value");
+      }
+      if (!isAbsolute(installDir)) {
+        throw new Error("--install-dir must be an absolute path");
+      }
+      continue;
+    }
+    if (argument === "--help" || argument === "-h") {
+      usage();
+      return null;
+    }
+    throw new Error(`unknown argument ${argument}`);
+  }
+
+  if (process.platform === "win32") {
+    throw new Error("the release installer supports Linux and macOS only");
+  }
+
+  return { installDir: installDir ? resolve(installDir) : undefined, version };
+}
+
+export function main(argumentsList) {
+  const options = parseArguments(argumentsList);
+  if (!options) {
+    return Promise.resolve();
+  }
+
+  const environment = { ...process.env };
+  if (options.version) {
+    environment.DELEGATION_LAYER_VERSION = options.version;
+  }
+  if (options.installDir) {
+    environment.DELEGATION_LAYER_INSTALL_DIR = options.installDir;
+  }
+
+  return new Promise((resolvePromise, reject) => {
+    const child = spawn("sh", [installerPath], {
+      env: environment,
+      stdio: "inherit",
+    });
+    child.on("error", reject);
+    child.on("exit", (code, signal) => {
+      if (code === 0) {
+        resolvePromise();
+        return;
+      }
+      reject(new Error(`CLI installer exited with ${signal ?? `status ${code}`}`));
+    });
+  });
+}

package/skills/agent-integration/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: agent-integration
+description: Use Delegation Layer from a provider-agnostic agent workflow, including capability discovery, bounded dispatch, terminal collection, and live authentication handling.
+---
+
+# Agent integration
+
+This skill is self-contained as an operating guide. It gives an agent enough
+information to prepare a safe run, choose a provider from observed
+capabilities, and collect a terminal result when the host exposes the
+Delegation Layer CLI. It applies to every provider profile and does not encode
+provider names, release versions, or native CLI syntax.
+
+## Preconditions
+
+The host is responsible for installing and configuring the CLI and supervisor.
+This skill must not install, build, upgrade, or repair either one. It may check
+whether `delegate` is available, use a configured private supervisor
+configuration and socket, and create separate task and state directories that
+it is authorized to use.
+Authentication is a separate live gate; do not invent a provider-specific
+login check or classify a missing login as static incompatibility.
+
+Keep the supervisor configuration, Delegation Layer state root, and task
+workspace as separate canonical paths. Do not put credentials in a brief, task
+option, environment value recorded by the task, or agent-visible output.
+
+## Start safely
+
+First check that the already-installed CLI is available, then discover compiled
+profiles:
+
+```sh
+command -v delegate
+delegate help
+delegate providers --json
+```
+
+If `command -v delegate` fails, stop and report that the host prerequisite is
+missing. Do not install or build the CLI from this skill.
+
+`providers --json` is static discovery. It lists provider IDs, supported
+permission modes and options, and the help arguments and flags required by the
+compiled adapters. It does not inspect the host, authenticate a provider, or
+prove that a provider is launchable.
+
+Choose a listed `PROFILE`, then inspect its provider-neutral contract:
+
+```sh
+delegate capabilities --provider PROFILE --json
+```
+
+This command is side-effect-free. It does not create state, contact Pueue, or
+launch a provider. A successful catalog response has
+`status: "unknown"`, `verification: "catalog"`, and
+`live_acceptance.status: "not_run"`. Unknown here means that dispatch has not
+run the host probe yet; it is neither a compatibility failure nor live proof.
+
+Choose a listed `PROFILE`, ensure its provider executable is available to the
+dispatch environment, and prepare a finite brief and two separate absolute
+directories. Then dispatch one bounded task:
+
+```sh
+mkdir -p "${HOME}/delegation-workspace" "${HOME}/delegation-state"
+printf '%s\n' 'Inspect the workspace and return a short summary.' > "${HOME}/delegation-brief.txt"
+
+delegate --root "${HOME}/delegation-state" \
+  --pueue-config /absolute/path/to/private-pueue.yml \
+  dispatch \
+  --provider PROFILE \
+  --brief "${HOME}/delegation-brief.txt" \
+  --cwd "${HOME}/delegation-workspace" \
+  --permission read-only \
+  --budget 30m \
+  --json
+```
+
+Use the host's configured private supervisor path (or its
+`DELEGATE_PUEUE_CONFIG` equivalent); the placeholder above is not a path to
+create. If the supervisor or provider executable is unavailable, stop on the
+CLI's structured error. For live acceptance, an unavailable authentication
+prerequisite is `blocked`; preserve that evidence and never relabel it as
+incompatible or passed.
+
+Save the returned `task_id`. Admission records one immutable request and at
+most one provider launch attempt; the command does not wait for completion.
+Observe and collect with that exact ID:
+
+```sh
+delegate --root "${HOME}/delegation-state" status TASK_ID --json
+delegate --root "${HOME}/delegation-state" collect TASK_ID --watch 5s --json
+```
+
+Repeat `collect` while the task is pending. Collection is observational: it
+may wait for the bounded watch interval and clean up a validated reservation,
+but it never launches, retries, or resumes provider work. A continuation is a
+new task with an exact predecessor ID when the selected profile advertises
+continuation support.
+
+## Read the JSON contract
+
+The capability response has this stable shape. The two arrays are
+profile-specific and can be non-empty; empty arrays below only keep the example
+provider-agnostic:
+
+```json
+{
+  "schema_version": 1,
+  "command": "capabilities",
+  "capability": {
+    "contract": "runtime-capability-v1",
+    "provider": "PROFILE",
+    "status": "unknown",
+    "verification": "catalog",
+    "help_args": [],
+    "required_flags": [],
+    "reason_code": "runtime_probe_not_run",
+    "live_acceptance": {
+      "status": "not_run",
+      "authentication": "unknown",
+      "reason_code": "runtime_probe_not_run"
+    }
+  }
+}
+```
+
+Interpret the fields as follows:
+
+- `status=unknown` with `verification=catalog` is a declaration from the
+  compiled catalog.
+- `status=ready` with `verification=runtime` appears in a dispatch response
+  only after the supervised probe observed the required behavior and exact
+  executable identity for that admission boundary.
+- `status=unsupported` is a machine-readable refusal. Use `reason_code` and
+  the bounded error to explain it; do not try another profile without a new
+  explicit selection.
+- `version` is diagnostic observation. Accept any valid nonempty trimmed UTF-8
+  version text. Never use a release allowlist, semantic-version comparison, or
+  web lookup as a compatibility decision. Required flags, executable identity,
+  and provider behavior decide compatibility. An unusually large version may
+  be omitted from the bounded projection.
+- `live_acceptance` is separate from compatibility. `not_run` does not claim a
+  live test; `passed` requires authenticated provider evidence; `blocked` means
+  authentication or another prerequisite was unavailable and is neutral. A
+  blocked result must never be reported as a pass or as incompatible behavior.
+
+Dispatch JSON contains the same `capability` projection plus separate task
+`admission`, `liveness`, and `publication` fields. Read those fields
+independently. Trust a terminal `outcome` only after it has been returned by
+the validated collection path and its payload and sealed evidence descriptors
+match the task records.
+
+## Integration acceptance contract
+
+Apply these criteria to every provider and every agent integration:
+
+- required behavior is verified at the runtime boundary;
+- arbitrary valid provider version text remains acceptable;
+- missing flags, executable identity drift, malformed facts, and timeouts fail
+  closed;
+- authentication is represented separately from compatibility;
+- missing authentication is `blocked`, never a passing skip;
+- admission is at most once and collection is observational;
+- terminal results come from durable validated evidence; and
+- JSON output is bounded, deterministic for observational commands, versioned,
+  and free of credentials.
+
+Do not expose credentials, tokens, private raw provider output, or unrestricted
+diagnostics in prompts, tool results, receipts, or task metadata. After an
+uncertain admission or lost response, inspect the original task with
+`status`/`collect`; do not relaunch it. Stop and report the durable state when
+the task cannot be resolved from validated evidence.
+
+## Completion record
+
+An integration is complete when it can provide:
+
+- the selected profile and original task ID;
+- the bounded capability and dispatch JSON responses;
+- the terminal committed or rejected outcome and validated evidence
+  descriptors; and
+- a sanitized live-acceptance receipt marked `passed`, `failed`, or `blocked`.