feat(deps): commit file-based secure-exec deps with transient publish-time version swap

.claude/skills/bump-secure-exec/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: bump-secure-exec
+description: Advance agent-os's committed secure-exec dependency by bumping the .github/refs/secure-exec sha. Use whenever agent-os needs newer secure-exec (e.g. after a secure-exec PR merges).
+---
+
+# Bump the secure-exec ref
+
+The committed deps are file-based (`link:`/`path` at `../secure-exec`); the
+ONLY committed version state is the sha in `.github/refs/secure-exec`.
+
+1. Bump it (defaults to the sibling `../secure-exec` checkout's current commit;
+   normally pass the merged secure-exec main sha):
+
+   ```bash
+   just secure-exec-bump [sha]
+   ```
+
+2. Commit + push on the current bookmark:
+
+   ```bash
+   jj describe -m "chore(deps): bump secure-exec ref" && jj bookmark set <bm> -r @ && jj git push
+   ```
+
+3. CI clones + builds `../secure-exec` at that sha (cached per sha). The FIRST
+   run per sha is slow — full native wasm build — then cached.
+
+Rules:
+- The sha must be reachable in rivet-dev/secure-exec (merged to main, or a
+  pushed branch). Prefer main-merged shas — squash-merges orphan branch commits.
+- Never commit published-version pins instead; `verify-file-deps` fails the
+  branch. If a swap leaked locally: `node scripts/secure-exec-dep.mjs
+  release-revert && pnpm install`.

.claude/skills/release-preview/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: release-preview
+description: Cut an agent-os release-preview end-to-end — bump the committed .github/refs/secure-exec sha if needed, then dispatch the preview (which auto-cuts the secure-exec preview at that sha). Use when the user asks for a preview, release-preview, or to hand off a secure-exec change via an agent-os preview build.
+---
+
+# Release-preview (agent-os preview, auto-cutting the secure-exec preview)
+
+End-to-end loop for validating secure-exec changes through an agent-os preview.
+Both repos use their unified `.github/workflows/publish.yaml`
+(workflow_dispatch, no `version` input = preview = debug build, npm-only,
+dist-tag = sanitized branch name).
+
+The agent-os committed dependency state is FILE-BASED (`link:`/`path` at
+`../secure-exec` + the `.github/refs/secure-exec` sha — see agent-os CLAUDE.md
+"Boundaries"). You never pin versions on a branch; the agent-os publish
+workflow swaps to published versions transiently (`secure-exec-dep.mjs
+release-swap`) inside its own checkout.
+
+## Procedure
+
+1. **Push the secure-exec changes** to a secure-exec branch (jj colocated;
+   commit with `jj --config snapshot.max-new-file-size=16777216 ...` if large
+   assets complain). Merge to main if they are ready — the ref pin works with
+   any reachable sha.
+
+2. **Point agent-os at that sha and push**:
+
+   ```bash
+   cd <agent-os>
+   just secure-exec-bump <secure-exec-sha>   # writes .github/refs/secure-exec
+   jj describe -m "chore(deps): bump secure-exec ref" && jj bookmark set <bm> -r @ && jj git push
+   ```
+
+   PR CI clones + builds `../secure-exec` at that sha (cached per sha) — no
+   publish needed for CI to go green.
+
+3. **Cut the release-preview**:
+
+   ```bash
+   just release-preview <agent-os-branch>
+   run=$(gh run list -R rivet-dev/agentos --workflow=publish.yaml -L1 --json databaseId --jq '.[0].databaseId')
+   gh run watch -R rivet-dev/agentos "$run" --exit-status
+   ```
+
+   The workflow's `secure-exec-version` job automatically cuts (or reuses) a
+   secure-exec preview at the committed ref sha — branch `agentos-dep-<sha7>`,
+   npm version `0.0.0-agentos-dep-<sha7>.<sha7>`, registry packages under the
+   same dist-tag — then every job release-swaps to those versions before
+   building/publishing. Requires the `SECURE_EXEC_DISPATCH_TOKEN` secret on the
+   agent-os repo (workflow rights on secure-exec).
+
+## Releases
+
+`just release --secure-exec-version <v>` — `<v>` MUST be a real secure-exec
+release (verified on npm AND crates.io) so agent-os npm packages and crates.io
+crates reference the same secure-exec. Cut a secure-exec release first if
+needed. Release-preview is for previews ONLY; never cut a release with it.
+
+## Loop-until-green
+
+On any failure: `gh run view <run> --log-failed`, fix the root cause, re-dispatch,
+re-watch. If the auto-cut secure-exec preview half fails, its run is in
+rivet-dev/secure-exec's actions under branch `agentos-dep-<sha7>`.
+
+## If a swap ever leaks into the working tree
+
+```bash
+node scripts/secure-exec-dep.mjs release-revert && pnpm install
+```

.claude/skills/release/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: release
-description: Cut a release or trigger a preview publish via the scripts/publish flow. Use when the user asks to release, publish, cut a release, bump the version, or preview-publish a branch.
+description: Cut a release or a release-preview via the scripts/publish flow. Use when the user asks to release, publish, cut a release, bump the version, or preview a branch.
 ---
 
 # Release
@@ -10,16 +10,21 @@ The publish flow lives in `scripts/publish` and is driven by the unified
 
 - **Release** — a versioned cut that publishes to npm + crates.io, creates a
   GitHub release with binaries, and tags `v<version>`.
-- **Preview publish** — a branch snapshot published to npm only, under a
+- **Release-preview** — a branch snapshot published to npm only, under a
   branch-named dist-tag, using fast debug builds. No git tag, no crates.io
   release, no GitHub release.
 
 ## Release
 
+A release REQUIRES a real secure-exec release version (the committed deps are
+file-based; the workflow verifies `<v>` on npm AND crates.io and release-swaps
+to it transiently — cut one first with secure-exec's `release-secure-exec`
+skill if needed):
+
 ```bash
-just release --version 0.2.0          # exact version
-just release --version 0.2.0-rc.1     # rc (npm tag `rc`, prerelease)
-just release --patch                  # semver bump from latest git tag
+just release --secure-exec-version <v> --version 0.2.0       # exact version
+just release --secure-exec-version <v> --version 0.2.0-rc.1  # rc (npm tag `rc`)
+just release --secure-exec-version <v> --patch               # semver bump from latest git tag
 ```
 
 `just release` runs `scripts/publish/src/local/cut-release.ts`, which:
@@ -28,20 +33,26 @@ just release --patch                  # semver bump from latest git tag
 3. Rewrites `Cargo.toml` + every publishable `package.json` version.
 4. Runs a local core build + type-check fail-fast (`--skip-checks` to skip).
 5. Commits + pushes the version bump.
-6. Triggers `publish.yaml` with the version, which builds release binaries,
-   publishes npm + crates.io, uploads release assets, and tags `v<version>`.
+6. Triggers `publish.yaml` with the version + `secure_exec_version`, which
+   verifies the secure-exec release, release-swaps the file deps to it in the
+   CI checkout (never committed), builds release binaries, publishes npm +
+   crates.io, uploads release assets, and tags `v<version>`.
 
 Flags: `--latest` / `--no-latest`, `--dry-run` (mutate files only), `-y`.
 
-## Preview publish
+## Release-preview
 
 ```bash
-just preview-publish <branch>
+just release-preview <branch>
 ```
 
 Dispatches `publish.yaml` on the branch with no version. The context resolver
 computes `version = 0.0.0-<sanitized-branch>.<sha>` and `npm_tag = <sanitized-branch>`,
 builds a debug sidecar, and publishes every package to npm under that tag.
+The `secure-exec-version` job auto-cuts (or reuses) a secure-exec preview at
+the committed `.github/refs/secure-exec` sha and release-swaps to it — see the
+`release-preview` skill for the end-to-end cross-repo loop (needs the
+`SECURE_EXEC_DISPATCH_TOKEN` secret).
 Install a preview with:
 
 ```bash

.github/refs/README.md

@@ -0,0 +1,16 @@
+# Sibling checkout refs
+
+Each file here pins the full 40-char git sha of a sibling repository that this
+repo's COMMITTED file-based dependencies (`link:`/`path` deps) resolve against.
+CI materializes each sibling at its pinned sha; dev machines use their own
+checkout at whatever state they're hacking on.
+
+- `secure-exec` — the sha of `rivet-dev/secure-exec` that `../secure-exec`
+  link:/path deps build against. Bump with `just secure-exec-bump [sha]`
+  (see the `bump-secure-exec` skill); read by
+  `scripts/secure-exec-dep.mjs prepare-build` (CI clone), the `verify-file-deps`
+  gate, the sibling build cache key in `ci.yml`, and the `secure-exec-version`
+  job in `publish.yaml` (preview auto-cut identity `agentos-dep-<sha7>`).
+
+Never edit these by hand — use the bump recipes so the sha is validated and
+fully resolved.

.github/refs/secure-exec

@@ -0,0 +1 @@
+496af27ace89bcb838042a4fb8542a9b9ce494ae

.github/workflows/ci.yml

@@ -34,6 +34,19 @@ jobs:
           git -C /tmp/docs-theme checkout 450c498555135098c6a927adfdf13458be9be22a
           rm -rf website/vendor/theme && mkdir -p website/vendor
           cp -r /tmp/docs-theme/packages/theme website/vendor/theme
+      # The committed dependency state is FILE-BASED: @secure-exec/* and
+      # @agentos-software/* resolve via link:/path into the sibling
+      # ../secure-exec, materialized here at the committed .github/refs/secure-exec sha.
+      # The whole built sibling is cached on that sha, so only a ref bump pays
+      # the full secure-exec build (native wasm included).
+      - run: node scripts/verify-file-deps.mjs
+      - name: Cache secure-exec sibling
+        uses: actions/cache@v4
+        with:
+          path: ../secure-exec
+          key: secure-exec-sibling-${{ runner.os }}-${{ hashFiles('.github/refs/secure-exec') }}
+      - name: Prepare secure-exec sibling (clone at .github/refs/secure-exec + build)
+        run: node scripts/secure-exec-dep.mjs prepare-build --build
       - run: pnpm install --frozen-lockfile
       - run: npx turbo build --filter='!@agentos/website'
       - run: pnpm --dir scripts/publish run check-types
@@ -50,13 +63,8 @@ jobs:
       - run: node scripts/check-secure-exec-package-boundary.mjs
       - run: node --test scripts/check-no-escaping-local-deps.test.mjs
       - run: node scripts/check-no-escaping-local-deps.mjs
-      # Build the Rust crates against the pinned secure-exec. For a preview pin this
-      # clones secure-exec at the pinned <sha> and switches cargo to local path deps
-      # (crates.io has no preview track, so an unreleased crate API — e.g. a new
-      # Extension hook — is only reachable via the clone); no-op for release pins.
-      # Mirrors the same step in publish.yaml so PR CI matches the build.
-      - name: Prepare secure-exec crates
-        run: node scripts/secure-exec-dep.mjs prepare-build
+      # The committed cargo deps are path deps into ../secure-exec, prepared by
+      # the sibling step above (which also syncs the crate version requirement).
       - run: cargo fmt --check
       - run: cargo clippy --workspace --all-targets -- -D warnings
       - run: cargo test -p agentos-protocol -- --test-threads=1