eval: prove native Agent Spec resources

agent-session-id: dev3.dotfiles-cos-misc-st2-resource-design
agent-tool: Codex
agent-tool-version: 0.145.0
agent-model: gpt-5.6-sol
agent-runtime-profile: /home/schickling/.local/state/agent-session-recovery/2026-07-29-pty-st2-cutover/runtime-profile/profile-without-null-opencode.json
agent-skills-manifest: /nix/store/kx5j47nghj1yps2v693ryb6wnf1c2xhb-agent-skills-corpus/share/agent-skills/manifest.json
tooling-profile: dotfiles@16a22c6

Author: schickling-assistant

AGENT-SPEC.md

@@ -1,8 +1,8 @@
 # Canonical st2 agent specification
 
 This is the sole agent-authoring specification for this repository. It is pinned to st2
-[`9887b2842222def0838c2cd82e6c24c218f7efa6`](https://github.com/compoundingtech/st2/commit/9887b2842222def0838c2cd82e6c24c218f7efa6)
-(`0.1.0`, source `9887b28`). It documents the hand-authored KDL accepted at that commit. Do not infer
+[`0fed14bb5653b67e1d64f1199e240c4c5c612bf7`](https://github.com/compoundingtech/st2/commit/0fed14bb5653b67e1d64f1199e240c4c5c612bf7)
+(`0.1.0+0fed14b`, source `0fed14b`). It documents the hand-authored KDL accepted at that commit. Do not infer
 additional fields or commands from older corpus fixtures.
 
 st2 runs long-lived `service` agents made of interactive `pty` tasks and terminal-free `exec` tasks.
@@ -46,6 +46,8 @@ agent "<identity>" {
   retired #false
   keep #false
 
+  resource "work" _tag="github-issue" uri="github-issue://example/project/123"
+
   restart {
     attempts 3
     interval "60s"
@@ -82,6 +84,7 @@ Supported agent children are:
 | `supervisor "…"` | Optional bare identity or full bus id for crash-loop routing. |
 | `retired #true` | Decommission the declaration on the next reconciliation. Edit this flag; do not delete a live declaration to retire it. |
 | `keep #true` | Freeze dead evidence and suppress collection/restart for every task; retirement still stops live tasks. |
+| `resource "name" _tag="type" uri="absolute-uri"` | Binds one uniquely named, externally identified Resource as declaration metadata. |
 | `restart { … }` | Optional service restart policy. |
 | `env { KEY "value" }` | Environment inherited by the compact agent task and sidecars. |
 | `command "…"` | Compact interactive task named `agent`. |
@@ -100,6 +103,41 @@ the window reset; `mode "fail"` parks the task after attempts are exhausted and
 crash-loop message to `supervisor`. Invalid restart subfields currently fall back to defaults; authors must not
 rely on that permissiveness.
 
+## Resource bindings
+
+An agent may directly carry zero or more Resource bindings:
+
+```kdl
+resource "work" _tag="github-issue" uri="github-issue://example/project/123"
+resource "source" _tag="worktree" uri="worktree://example/project/main"
+```
+
+The positional name is the Resource's agent-local semantic role. Names are non-empty and unique within one
+agent. `_tag` is a non-empty, opaque discriminator owned by the Resource type's downstream contract. `uri` is
+an RFC 3986 absolute URI and is the Resource identity. st2 preserves the URI's exact bytes; it does not
+normalize or resolve it. Declaration order has no meaning. Canonical KDL and supported TOML/JSON parsing lower
+bindings to deterministic name order.
+
+The generic envelope is closed: each binding has exactly the positional name, `_tag`, and `uri`. Missing or
+duplicate fields, duplicate names, child nodes, invalid URI syntax, and unsupported properties such as access
+or readiness policy fail validation. This prevents an ignored property from appearing enforced.
+
+Resource bindings are declaration metadata, not launch targets. They do not make an otherwise unrunnable
+service runnable and are excluded from effective task launch definitions. Editing only Resource bindings
+therefore updates catalog inspection while an already-live task is adopted without stop, replacement, or
+relaunch. `st2 agents --json [--enrich]` exposes every binding as a name-ordered
+`{"name","_tag","uri"}` descriptor and preserves unknown downstream tags.
+
+The envelope does not define Resource schemas, resolution, access grants, required/optional status, readiness,
+lifecycle, mutation, or rendering. A URI's presence grants no authority. Those semantics belong to the
+concrete Resource type and its consumer, not st2.
+
+Executable evidence:
+[`agent-spec-resource-bindings`](cells/agent-spec-resource-bindings/) covers strict parser failures,
+deterministic JSON inspection, exact URI and unknown-tag preservation, Resource-only live adoption, and
+cleanup. The matched [`assignment-contract-*`](cells/) tournament covers direct Resource selection against
+Focus and Assignment controls; direct bindings are the selected treatment.
+
 ## Compact and explicit tasks
 
 The canonical compact pair:
@@ -392,7 +430,7 @@ Codex launch explicitly selects `gpt-5.6-sol` at medium reasoning effort.
 
 The folder-eval grammar preserves its `team`, `eval`, kickoff, timeout, and held-out judge shape. Its
 agent projection supports `workspace`, `supervisor`, `env`, `command`, explicit `exec`, and bare
-`ding`; it does not accept a catalog `render` block. For that grammar, `eval { copy … }` and a
+`ding`; it does not accept catalog `resource` or `render` nodes. For that grammar, `eval { copy … }` and a
 deterministic pre-boot materializer must place the equivalent harness files in each declared
 workspace:
 
@@ -415,9 +453,9 @@ agent { command "true" }
 At the pinned source it validates as one agent with zero errors and warnings. Production declarations should
 normally make identity, host, `ST_AGENT`, workspace, and the real harness command explicit.
 
-The complete declaration, compact pair, explicit PTY/exec blocks, restart policy, and render block earlier in
-this document collectively exercise every implemented authoring field. Before validating/materializing the
-example, create every `$CATALOG`-rooted workspace it names.
+The complete declaration, Resource bindings, compact pair, explicit PTY/exec blocks, restart policy, and
+render block earlier in this document collectively exercise every implemented authoring field. Before
+validating/materializing the example, create every `$CATALOG`-rooted workspace it names.
 
 ## Free authoring gate
 
@@ -432,8 +470,11 @@ Inspect the declaration, every referenced template, and every workspace destinat
 materialization command. Materialization is byte-idempotent and does not imply hook installation. Starting
 the network is a separate, explicitly authorized action.
 
-For source `9887b28`, the accepted Linux executable has SHA256
-`d49d44fd4f3f6f655455c212353a469fefa956082bedf22163deb767d8a36a0d`; its published archive has SHA256
-`32ee103bd17ccb3e155ac63d816a3906c2470a3c98e3cc04b56e5a67138b9927`. `bin/check-corpus.sh` verifies
-the variable-age version contract, exact installed binary, embedded full source commit, strict semantic
-validation, fixture resets, and the rest of the model-free corpus gate before an eval may run.
+For source `0fed14b`, the accepted pre-merge Nix-built Linux executable has SHA256
+`96b394f270f0a3eb25dd29574a96f30d527a56bee63c2499d6db7e4a58707648`. There is no published portable
+archive for this unmerged commit. After `compoundingtech/st2#86` merges, this pin must move to its accepted
+release and record the fresh-download archive hash before the corpus is ready. `bin/check-corpus.sh` verifies
+the variable-age Nix version contract, exact installed candidate binary, strict semantic validation, fixture
+resets, and the rest of the model-free corpus gate before an eval may run. The pre-merge Nix stamp embeds only
+the short revision, so the full source link above is review/build provenance rather than a claim extracted
+from the binary; the post-merge portable release must restore fresh-download full-source proof.

CATALOG.md

@@ -1,7 +1,7 @@
 <!-- Generated by bin/generate-catalog.sh from cell KDL and evidence/*.tsv. Do not edit. -->
 # Current eval catalog and evidence
 
-This is the sole current corpus surface: **53 included cells** (13 model-free,
+This is the sole current corpus surface: **54 included cells** (14 model-free,
 40 model-backed) and **4 retired exclusions**. Inventory fields are derived from the active
 KDL and executable judge scripts. Latest accepted PASS evidence remains distinct from the append-only run
 history: a failed last run is visible without being advertised as accepted evidence, and cells with no
@@ -16,6 +16,7 @@ harness-native loader plus canonical hook file.
 
 | Cell | Harness | Model(s) / effort | Model seats | Cost | Timeout | Held-out judges | Latest accepted PASS | Last recorded run |
 |---|---|---|---:|---|---|---:|---|---|
+| `agent-spec-resource-bindings` | model-free | — | 0 | none | `60s` | 4 | — | **NO STRUCTURED RUN** |
 | `assignment-contract-cold-assignment` | Codex | `gpt-5.6-sol` / medium | 2 | medium | `1200s` | 3 | — | **NO STRUCTURED RUN** |
 | `assignment-contract-cold-focus` | Codex | `gpt-5.6-sol` / medium | 2 | medium | `1200s` | 3 | — | **NO STRUCTURED RUN** |
 | `assignment-contract-cold-resources` | Codex | `gpt-5.6-sol` / medium | 2 | medium | `1200s` | 3 | — | **NO STRUCTURED RUN** |
@@ -89,6 +90,7 @@ while the last-run column makes a recorded failure distinct from a cell with no
 
 ## Harness hook exclusions
 
+- `agent-spec-resource-bindings` / `cell` — deterministic native Agent Spec Resource-envelope probe; no harness seat
 - `context-resource-continuity` / `cell` — deterministic native context/resource restart probe; no harness seat
 - `docs` / `judge:cold-reader` — one-shot offline Claude print grader; no bus identity, DING, or hook surface
 - `exec-lifecycle-logging` / `cell` — deterministic native exec lifecycle probe; no harness seat
@@ -104,7 +106,7 @@ while the last-run column makes a recorded failure distinct from a cell with no
 - `st2-network` / `cell` — deterministic catalog/message round-trip probe; no harness seat
 - `two-networks-coexist` / `cell` — deterministic catalog-isolation probe; no harness seat
 
-These **14** rows are generated from structured exclusions. A cell-level row is required for
+These **15** rows are generated from structured exclusions. A cell-level row is required for
 every derived model-free cell. The one-shot docs cold reader is a model-backed grader, but not a bus-connected
 agent: it has no st2 identity, DING sidecar, or lifecycle hooks.
 

README.md

@@ -96,7 +96,7 @@ VERDICT: PASS
 ```
 
 Requirements are `st2 0.1.0` from source
-[`9887b28`](https://github.com/compoundingtech/st2/commit/9887b2842222def0838c2cd82e6c24c218f7efa6),
+[`0fed14b`](https://github.com/compoundingtech/st2/commit/0fed14bb5653b67e1d64f1199e240c4c5c612bf7),
 `pty`, Bash, Git, `jq`, Rust/Cargo for the pinned KDL parser gate, and Node for JavaScript fixtures. A paid cell
 also needs every harness named by its dry-run row.
 
@@ -122,6 +122,17 @@ current bus-connected model agent.
 Team-less cells use deterministic `run` steps and judges without a model. Current examples cover native hook
 materialization, network health, catalog/pty isolation, and pty send/peek behavior.
 
+## Native Resource-envelope acceptance
+
+`agent-spec-resource-bindings` is the model-free companion to
+[`compoundingtech/st2#86`](https://github.com/compoundingtech/st2/pull/86). It exercises native catalog
+declarations rather than the tournament's synthetic Resource documents. The cell proves strict envelope
+validation, deterministic `st2 agents --json` inspection, opaque downstream tags, exact URI preservation, and
+adoption of a live task after a Resource-only declaration edit.
+
+Folder-eval Resource projection, Resource resolution, access, readiness, and lifecycle policy are outside this
+cell. The portable Agent Spec envelope does not imply any of them.
+
 ## Resource-binding tournament
 
 The nine `assignment-contract-*` cells form one matched tournament over three lifecycle scenarios and three

bin/check-corpus.sh

@@ -5,10 +5,9 @@ set -euo pipefail
 repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 cd "$repo_root"
 
-expected_source="9887b28"
-expected_source_full="9887b2842222def0838c2cd82e6c24c218f7efa6"
-expected_binary_sha256="d49d44fd4f3f6f655455c212353a469fefa956082bedf22163deb767d8a36a0d"
-expected_version_regex='^st2 0\.1\.0 — running from local source \(9887b28, .+ ago\)$'
+expected_source="0fed14b"
+expected_binary_sha256="96b394f270f0a3eb25dd29574a96f30d527a56bee63c2499d6db7e4a58707648"
+expected_version_regex='^st2 0\.1\.0\+0fed14b — committed .+ ago$'
 st2_path="$(command -v st2)"
 actual_version="$(st2 --version)"
 [[ "$actual_version" =~ $expected_version_regex ]] || {
@@ -20,11 +19,7 @@ actual_binary_sha256="$(sha256sum "$st2_path" | awk '{ print $1 }')"
   echo "FAIL: expected st2 binary sha256 $expected_binary_sha256, found $actual_binary_sha256 at $st2_path" >&2
   exit 1
 }
-LC_ALL=C grep -aFq "$expected_source_full" "$st2_path" || {
-  echo "FAIL: st2 binary at $st2_path does not embed full pinned source $expected_source_full" >&2
-  exit 1
-}
-echo "PASS: pinned runner source $expected_source ($actual_version; sha256 $actual_binary_sha256)"
+echo "PASS: pinned pre-merge Nix candidate $expected_source ($actual_version; sha256 $actual_binary_sha256)"
 
 mapfile -d '' shell_files < <(
   find bin cells -type f -name '*.sh' -not -path '*/_git/*' -print0 | sort -z

cells/agent-spec-resource-bindings/README.md

@@ -0,0 +1,16 @@
+# agent-spec-resource-bindings
+
+Model-free acceptance coverage for the native Agent Spec Resource envelope introduced by
+[`compoundingtech/st2#86`](https://github.com/compoundingtech/st2/pull/86).
+
+The cell proves the catalog contract directly through st2:
+
+- Resource names are unique, `_tag` remains opaque, and `uri` must be an RFC 3986 absolute URI.
+- Unsupported policy properties fail closed instead of being silently ignored.
+- Canonical KDL and supported TOML/JSON forms project the same stable, name-ordered
+  `st2 agents --json` descriptors without normalizing URI bytes.
+- Editing only Resource bindings updates the declared roster while the existing PTY keeps the same process
+  identity and is adopted rather than stopped or relaunched.
+
+It does not exercise folder-eval Resource projection, resolution, access, readiness, or Resource lifecycle
+policy. Those are outside the portable envelope.

cells/agent-spec-resource-bindings/agent-spec-resource-bindings.kdl

@@ -0,0 +1,24 @@
+// Native Agent Spec Resource envelope: parse failures, roster projection, and nondisruptive adoption.
+eval {
+  copy "./fixture"
+  max-timeout "60s"
+
+  run "contract" {
+    command "bash ./contract.sh"
+  }
+
+  judges {
+    judge "STRICT ENVELOPE — malformed URI, duplicate names, and policy fields fail closed" {
+      exec "grep -Fqx RESOURCE-STRICT-FAILURES-GREEN-c214 $RUNS_DIR/contract.out"
+    }
+    judge "INSPECTION — agents JSON is deterministic and preserves opaque tags plus exact URI bytes" {
+      exec "grep -Fqx RESOURCE-INSPECTION-GREEN-c214 $RUNS_DIR/contract.out"
+    }
+    judge "ADOPTION — a Resource-only declaration edit updates inspection without replacing the live task" {
+      exec "grep -Fqx RESOURCE-NONDISRUPTIVE-ADOPTION-GREEN-c214 $RUNS_DIR/contract.out"
+    }
+    judge "CLEANUP — the catalog leaves no live or retained PTY state" {
+      exec "grep -Fqx RESOURCE-CLEANUP-GREEN-c214 $RUNS_DIR/contract.out"
+    }
+  }
+}

cells/agent-spec-resource-bindings/fixture/contract.sh

@@ -0,0 +1,125 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+root="${CATALOG:?CATALOG must be set}"
+net="$root/net"
+spec="$net/agents/rb/worker/agent.kdl"
+export PTY_ROOT="$net/pty"
+export XDG_STATE_HOME="$root/state"
+
+cleanup() {
+  if test -f "$spec"; then
+    sed -i '/role "worker"/a\\  retired #true' "$spec" 2>/dev/null || true
+    st2 up --once --catalog "$net" --host rb >/dev/null 2>&1 || true
+    PTY_ROOT="$PTY_ROOT" pty rm rb.worker >/dev/null 2>&1 || true
+  fi
+}
+trap cleanup EXIT
+
+for case_name in uri duplicate policy; do
+  output="$root/invalid-$case_name.out"
+  set +e
+  st2 validate --catalog "$root/invalid/$case_name" --host rb --strict >"$output" 2>&1
+  exit_code="$?"
+  set -e
+  test "$exit_code" -ne 0
+done
+grep -Fq 'must be an exact absolute URI' "$root/invalid-uri.out"
+grep -Fq "duplicate resource binding 'work'" "$root/invalid-duplicate.out"
+grep -Fq 'unsupported property `access`' "$root/invalid-policy.out"
+echo "RESOURCE-STRICT-FAILURES-GREEN-c214"
+
+st2 validate --catalog "$root/parity" --host rb --strict >/dev/null
+st2 agents --catalog "$root/parity" --host rb --json >"$root/parity.json"
+jq -e '
+  length == 3 and
+  [.[].identity] == ["rb.json", "rb.kdl", "rb.toml"] and
+  ([.[].resources] | unique | length) == 1 and
+  .[0].resources == [
+    {
+      "name": "context",
+      "_tag": "vendor-specific-v7",
+      "uri": "vendor+thing://authority/context%2Fone"
+    },
+    {
+      "name": "work",
+      "_tag": "github-issue",
+      "uri": "github-issue://example/project/41?view=exact%20bytes"
+    }
+  ]
+' "$root/parity.json" >/dev/null
+
+st2 validate --catalog "$net" --host rb --strict >/dev/null
+st2 agents --catalog "$net" --host rb --json >"$root/agents-before.json"
+st2 agents --catalog "$net" --host rb --json >"$root/agents-repeat.json"
+cmp "$root/agents-before.json" "$root/agents-repeat.json"
+jq -e '
+  length == 1 and
+  .[0].identity == "rb.worker" and
+  .[0].resources == [
+    {
+      "name": "context",
+      "_tag": "vendor-specific-v7",
+      "uri": "vendor+thing://authority/context%2Fone"
+    },
+    {
+      "name": "work",
+      "_tag": "github-issue",
+      "uri": "github-issue://example/project/41?view=exact%20bytes"
+    }
+  ]
+' "$root/agents-before.json" >/dev/null
+echo "RESOURCE-INSPECTION-GREEN-c214"
+
+st2 up --once --catalog "$net" --host rb >"$root/launch.out"
+grep -Fq 'launched (1): rb.worker' "$root/launch.out"
+before="$(
+  PTY_ROOT="$PTY_ROOT" pty list --json |
+    jq -cer '.[] | select(.name == "rb.worker" and .status == "running") | {name, pid, createdAt}'
+)"
+test -n "$before"
+
+sed -i \
+  's#resource "work" _tag="github-issue" uri="github-issue://example/project/41?view=exact%20bytes"#resource "work" _tag="github-pr" uri="github-pr://example/project/86?view=exact%20bytes"#' \
+  "$spec"
+sed -i \
+  '/resource "context"/a\\  resource "terminal" _tag="pty" uri="pty://rb/rb.worker"' \
+  "$spec"
+st2 validate --catalog "$net" --host rb --strict >/dev/null
+st2 up --once --catalog "$net" --host rb >"$root/adopt.out"
+grep -Fq 'adopted (1): worker' "$root/adopt.out"
+test -z "$(sed -n '/launched (/p;/torn down (/p' "$root/adopt.out")"
+after="$(
+  PTY_ROOT="$PTY_ROOT" pty list --json |
+    jq -cer '.[] | select(.name == "rb.worker" and .status == "running") | {name, pid, createdAt}'
+)"
+test "$after" = "$before"
+
+st2 agents --catalog "$net" --host rb --json >"$root/agents-after.json"
+jq -e '
+  .[0].resources == [
+    {
+      "name": "context",
+      "_tag": "vendor-specific-v7",
+      "uri": "vendor+thing://authority/context%2Fone"
+    },
+    {
+      "name": "terminal",
+      "_tag": "pty",
+      "uri": "pty://rb/rb.worker"
+    },
+    {
+      "name": "work",
+      "_tag": "github-pr",
+      "uri": "github-pr://example/project/86?view=exact%20bytes"
+    }
+  ]
+' "$root/agents-after.json" >/dev/null
+echo "RESOURCE-NONDISRUPTIVE-ADOPTION-GREEN-c214"
+
+sed -i '/role "worker"/a\\  retired #true' "$spec"
+st2 up --once --catalog "$net" --host rb >/dev/null
+PTY_ROOT="$PTY_ROOT" pty rm rb.worker >/dev/null 2>&1 || true
+trap - EXIT
+test "$(PTY_ROOT="$PTY_ROOT" pty list --json | jq 'length')" -eq 0
+echo "RESOURCE-CLEANUP-GREEN-c214"

cells/agent-spec-resource-bindings/fixture/invalid/duplicate/agents/rb/worker/agent.kdl

@@ -0,0 +1,7 @@
+agent "worker" {
+  host "rb"
+  workspace "$CATALOG"
+  resource "work" _tag="github-issue" uri="github-issue://example/project/41"
+  resource "work" _tag="github-pr" uri="github-pr://example/project/86"
+  command "true"
+}

cells/agent-spec-resource-bindings/fixture/invalid/policy/agents/rb/worker/agent.kdl

@@ -0,0 +1,6 @@
+agent "worker" {
+  host "rb"
+  workspace "$CATALOG"
+  resource "work" _tag="github-issue" uri="github-issue://example/project/41" access="write"
+  command "true"
+}

cells/agent-spec-resource-bindings/fixture/invalid/uri/agents/rb/worker/agent.kdl

@@ -0,0 +1,6 @@
+agent "worker" {
+  host "rb"
+  workspace "$CATALOG"
+  resource "work" _tag="github-issue" uri="not-an-absolute-uri"
+  command "true"
+}