Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .agents/skills/uzi-lander/references/renovate.md
Original file line number Diff line number Diff line change
Expand Up @@ -105,6 +105,13 @@ new version can break uzi or ship capabilities uzi should adopt.
lock-only bump. On your own branch (below), take the lock and run `task codex-pins:sync`,
which rewrites every registered Codex version and digest pin from it; keep the Codex
guardrail/conformance checks green.
- After the Codex adoption read, hand-update `agent/codex/codex-package.adopted`:
exactly `lock-sha256=<64 lowercase hex>` then `runtime-tag=<CODEX_TAG>`, each
followed by LF, with no other lines. Hash the raw lock bytes with
`shasum -a 256 agent/codex/codex-package.lock`; take the tag from that lock. Commit both as
regular files. Pin sync and Renovate must never update this assertion. A lock
edit invalidates it; review the edit before recording adoption again. CI validates
the committed assertion, not whether the read occurred (ADR-3512, #4172).
- Required PR CI covers the agent suite, the real-binary `test:codex-m4` on amd64 and the
worker-uid lane (`test-agent`). The required `codex-packaged-proof-gate` covers the strict
packaged proof on amd64 and the arm64 package check (`e2e/codex-proof/package-exec.sh`). The amd64 image builds run but are not required.
Expand Down
22 changes: 20 additions & 2 deletions .agents/skills/uzi-release/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ Do NOT bake step details that live in the repo into your head. Read the source o
- A green CI `report` confirms incident delivery only; inspect the failed phase, planned tag and uncited identities, then fix the cause. Prepare/watch failure still makes the run red.
- An unconfirmed push receipt stops watch before publication recovery or verification. Inspect remote refs, then run local watch/verify against the same tag/SHA; this branch does not run automatic publication retries.
- If promotion succeeds but diagnostics cannot be written, the cutter exits nonzero and retains its local stable tag. CI does not push; inspect local and remote refs before recovery.
- Before local fallback, finish or stop any CI release run, inspect remote main/tags and resolve interrupted publication on the same tag. No local/CI race. A Codex lock change blocks CI planning; perform the adoption read and cut locally. On abandon the range starts at the highest stable, so an already adopted change can still require local fallback.
- Before local fallback, finish or stop any CI release run, inspect remote main/tags and resolve interrupted publication on the same tag. No local/CI race. A Codex lock change without a valid committed adoption record blocks CI planning; perform the adoption read and commit the record, or cut locally. Abandon uses the highest stable boundary and checks the same HEAD record.
- Nightly RC attempts are scheduled for 01:47 Europe/Bucharest only when repository variable `RELEASE_NIGHTLY_ENABLED` is exact `true` (default off). Observed scheduler delays can move cuts into daytime (ADR-3512). The shared plan may no-op; scheduled tip waiting is capped at three hours and the original run date's 13:00 pre-push cutoff. Neither applies to manual dispatch or recovery of a pushed tag. Only the user decides activation. Enablement is rechecked at job boundaries; pausing may stop a not-yet-pushed attempt there, possibly red with `nightly-disabled`. Cancel an in-flight run explicitly for an immediate stop; pushed-tag recovery is unaffected. The bounded attempt journal reports release-commit CI without success polling or reruns; tagged-smoke and targeted assertion recovery use the bounded exception above.
- NEVER `docker compose -p uzi down -v` and never glob `uzi-` containers (see `CLAUDE.md` "Destructive operations"). This skill touches git, `gh`, and (if you have deploy access) `kubectl` only.
- Work on `main` in the repo root worktree; `release-cut.sh` makes its own throwaway worktree for a promote. Never check the root worktree out onto another branch.
Expand All @@ -36,7 +36,25 @@ Do NOT bake step details that live in the repo into your head. Read the source o

**Artifact membership.** Query the public OCI registry anonymously; no Packages PAT is needed. GitHub release and Actions evidence still uses `gh` read access. Pass `--ci` to the cutter in automation (also enabled by `CI=true`): an unknown worker-pin query or checkout identity refuses the cut. Local cuts retain a warning on query errors; a confirmed missing worker image always refuses.

`release-cut.sh --plan [--version X.Y.Z] [--abandon-train]` reports the scheduled RC decision without fetching or changing Git state, CHANGELOG or fragments. Shared validators remove temporary snapshots but may leave an empty `.uzi/scratch` directory. Refresh refs first. Read `OP` (`nextrc`, `new-base`, `noop`, `blocked`), `BASE`, `TAG`, `REASON`, `SHIPPING_COUNT`, `PREVIOUS_TAG`, `PUBLICATION_STATE`, and `HEAD_SHA`; exit 0 includes no-op/blocked plans and some instrument failures (API or fragment reads); exit 2 is reserved for Git/history instruments, exit 3 for usage. An open train continues, otherwise 0.x defaults to the next minor; automatic 1.x needs a policy. A Codex runtime lock change in the plan range blocks with `codex-runtime-needs-local-cut`: perform the adoption read above and cut locally. Failed, pending, missing or unreadable previous publication blocks even a no-op. Only non-metadata shipping changes count, and notes or dependency citations must make them releasable. This recommendation does not remove manual empty-delta cuts or replace exact-tip CI checks.
`release-cut.sh --plan [--version X.Y.Z] [--abandon-train]` reports the scheduled RC decision without fetching or changing Git state, CHANGELOG or fragments. Shared validators remove temporary snapshots but may leave an empty `.uzi/scratch` directory. Refresh refs first. Read `OP` (`nextrc`, `new-base`, `noop`, `blocked`), `BASE`, `TAG`, `REASON`, `SHIPPING_COUNT`, `PREVIOUS_TAG`, `PUBLICATION_STATE`, and `HEAD_SHA`; exit 0 includes no-op/blocked plans and some instrument failures (API or fragment reads); exit 2 is reserved for Git/history instruments, exit 3 for usage. An open train continues, otherwise 0.x defaults to the next minor; automatic 1.x needs a policy. A Codex runtime lock change in the plan range requires the committed adoption record below; a missing or invalid record blocks with `codex-runtime-needs-local-cut`. Perform the adoption read and commit the record, or cut locally. Failed, pending, missing or unreadable previous publication blocks even a no-op. Only non-metadata shipping changes count, and notes or dependency citations must make them releasable. This recommendation does not remove manual empty-delta cuts or replace exact-tip CI checks.

### Committed Codex adoption (#4172)

After reading the runtime release notes and reviewing its manifest, hand-update
`agent/codex/codex-package.adopted`. Use exactly two LF-terminated lines, no extras:

```text
lock-sha256=SHA256_OF_RAW_LOCK_BYTES
runtime-tag=CODEX_TAG_FROM_LOCK
```

Use `shasum -a 256 agent/codex/codex-package.lock` for the 64 lowercase hex digest;
copy the lock's `CODEX_TAG` value for the second line. Commit both as mode 100644.
Planning validates both blobs at its pinned HEAD, including the digest and tag;
worktree-only files, symlinks and malformed or stale records do not authorize it.
Pin sync and Renovate never write the record. A later lock edit needs a fresh
adoption assertion. This records the maintainer's review, not a review by CI;
publication, exact-tip coverage and release authorization remain separate gates.

## 2. Local fallback: cut inline with the deterministic scripts — do NOT dispatch a subagent
Once step 1 holds (nothing wanted left unmerged, `main` green on the tip), cut the release **inline as the lead**, driving three bundled scripts. Do NOT dispatch the `release` subagent for this: a background subagent spawns a watch and then idles, so every wait becomes a manual re-ping (the "agent keeps dying" ping-pong), while the steps that actually need judgment — flake-vs-defect, whether to rerun, authoring the CHANGELOG — are the lead's regardless. `.claude/agents/release.md` stays the MECHANICS reference (what each step proves, the signing traps, deploy verify), but the driver is the lead + scripts, not that agent.
Expand Down
47 changes: 44 additions & 3 deletions .agents/skills/uzi-release/scripts/release-cut.sh
Original file line number Diff line number Diff line change
Expand Up @@ -332,6 +332,47 @@ EOF

# --plan is deliberately before every fetch, index edit and release mutation.
# Scratch snapshots use the cutter's existing bounded validators and clean traps.
# The assertion records a maintainer's adoption read, not a review performed by CI.
# Read only regular blobs at the pinned commit; never execute assertion/lock content.
codex_adoption_record_matches() {
python3 -I - "$1" <<'PY'
import hashlib
import re
import subprocess
import sys


def blob(path):
entry = subprocess.check_output(
["git", "ls-tree", "-z", sys.argv[1], "--", path], stderr=subprocess.DEVNULL
)
metadata, name = entry.removesuffix(b"\0").split(b"\t")
mode, kind, oid = metadata.split(b" ")
if mode != b"100644" or kind != b"blob" or name != path.encode():
raise ValueError("expected a committed regular file")
return subprocess.check_output(
["git", "cat-file", "blob", oid.decode("ascii")], stderr=subprocess.DEVNULL
)


try:
lock = blob("agent/codex/codex-package.lock")
record = blob("agent/codex/codex-package.adopted")
fields = re.fullmatch(
rb"lock-sha256=([0-9a-f]{64})\nruntime-tag=(rust-v[0-9]+\.[0-9]+\.[0-9]+)\n",
record,
)
tags = [line.removeprefix(b"CODEX_TAG=") for line in lock.split(b"\n")
if line.startswith(b"CODEX_TAG=")]
valid = (fields is not None and len(tags) == 1
and fields[1] == hashlib.sha256(lock).hexdigest().encode("ascii")
and fields[2] == tags[0])
except (OSError, ValueError, subprocess.SubprocessError):
valid = False
sys.exit(0 if valid else 1)
PY
}

release_plan() (
export GIT_OPTIONAL_LOCKS=0
git() { command git -c core.fsmonitor=false "$@"; }
Expand Down Expand Up @@ -382,13 +423,13 @@ release_plan() (
fi
tag="v$base-rc.1"; op='new-base'
fi
# Adoption still needs a local review/cut. Check before the publication refusal,
# which an explicitly authorized supersede may lift in the CI orchestrator.
# Adoption requires a matching committed assertion, or a local cut. Check before
# the publication refusal, which authorized supersede may lift independently.
git diff --quiet --no-ext-diff --no-textconv "$previous" "$head" -- agent/codex/codex-package.lock
runtime_rc=$?
case "$runtime_rc" in
0) : ;;
1) block_plan codex-runtime-needs-local-cut ;;
1) codex_adoption_record_matches "$head" || block_plan codex-runtime-needs-local-cut ;;
*) return 2 ;;
esac
# Check the previous publication even for a zero-delta scheduled attempt.
Expand Down
2 changes: 1 addition & 1 deletion .claude/agents/release.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ NOT modify source code.

## For this repo (uzi)

**Standard releases use `release-auto.yml` for manual dispatch and opt-in nightly RCs** with shared cutter/watch/verify scripts. See [ADR-3512](../../adr/3512-release-automation.md) and `deploy/README.md`. The RC App atomically pushes metadata and an RC tag; stable requires a pinned candidate and human Environment approval. Agents never dispatch `kind=stable` or approve `release-stable`. This agent is a mechanics reference, not a background release driver. Local fallback remains inline with the lead after finishing/stopping CI release work and inspecting remote main/tags. Codex adoption exceptions require the adoption read and a local cut.
**Standard releases use `release-auto.yml` for manual dispatch and opt-in nightly RCs** with shared cutter/watch/verify scripts. See [ADR-3512](../../adr/3512-release-automation.md) and `deploy/README.md`. The RC App atomically pushes metadata and an RC tag; stable requires a pinned candidate and human Environment approval. Agents never dispatch `kind=stable` or approve `release-stable`. This agent is a mechanics reference, not a background release driver. Local fallback remains inline with the lead after finishing/stopping CI release work and inspecting remote main/tags. Codex lock changes require the adoption read and a matching committed adoption record for CI planning; missing or invalid records retain the local-cut refusal (uzi-release, ADR-3512).

**RC-first release train (PRD #1265).** A release is cut as a CANDIDATE `vX.Y.Z-rc.1` by default and PROMOTED from that candidate. CI stable promotion stops there; the local --promote verb can couple the next candidate. `release-cut.sh` is a tag-derived state machine: default cuts the next RC (or refuses, exit 3, with the facts when a lower RC is in flight, so the lead asks the user to promote / re-spin / abandon); `--promote` creates the stable `vB` tag LOCALLY from a throwaway `release/B` worktree at the RC commit (metadata-only, a diff allowlist checked before any tag exists) and then cuts the next `vX.Y.Z-rc.1` on main; `--promote-only` (given the in-flight base `B`) runs that promote half alone: `vB` from the RC commit, no next candidate, `main` untouched, one push (the stable tag), for when `main` carries work not wanted in a candidate yet; `--skip-promote` abandons the RC; `--stable` is the old one-step cut, refused while an RC is in flight. An RC tag publishes images + chart at `X.Y.Z-rc.1`, a Release flagged pre-release (never latest), and the opt-in `uzi-cli-rc` Homebrew formula (PRD #1378: `brew.yml` triggers on every `v*` tag and routes an RC to the separate `uzi-cli-rc` formula, so stable users on `uzi-cli` never see a candidate; before #1378 its trigger excluded `v*-*` and cut no RC formula). **Push order on a promote is the STABLE tag, then `main`, then the RC tag** (the RC's `assert-changelog` derives its coverage base from the tags it can see and needs the new stable visible first); `release-cut.sh` prints the three lines in order. A deployment opts into running candidates with the chart range `0.*-0` instead of `0.*` (out of tree; `deploy/README.md`).

Expand Down
14 changes: 10 additions & 4 deletions adr/3512-release-automation.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,10 +67,16 @@ flowchart LR
cutter still validates releasability. Supersede lifts only the matched latest
failed/missing publication refusal, never pending/unreadable state or another
guard. It cannot waive coverage, oracle, metadata, pin or adoption checks.
- Codex lock changes require the adoption read and a local cut. No model or
attestation parsing runs in CI. Abandon uses the highest stable boundary, so
an adopted Codex change in an abandoned train still blocks automatic abandon
until a local cut. This is deliberate fail-closed behavior.
- Codex lock changes require the adoption read. CI accepts a maintainer-reviewed
`agent/codex/codex-package.adopted` assertion binding the raw lock SHA256 and
runtime tag to regular-file blobs at the same pinned HEAD (#4172). Its exact
two-line format is documented in the uzi-release skill. Missing or invalid
assertions retain `codex-runtime-needs-local-cut`; pin sync and Renovate never
certify adoption. This records the maintainer's read, not a read performed by CI.
Abandon still uses the highest stable boundary and validates the same HEAD
assertion. Publication, coverage and authorization gates remain independent.
This supersedes #3524's unconditional local-cut requirement with the
maintainer's acknowledgement; no model, PR-body parsing or new authority is added.
- A thin bundle requires its pinned parent to be fetched before verification.
Validate digest, exact refs, release SHA, tag object and single parent before
minting. No configuration or hooks are imported. A lost push receipt is
Expand Down
2 changes: 2 additions & 0 deletions agent/codex/codex-package.adopted
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
lock-sha256=0fee0e06f81e2cd2ce19f6f7de121a3a11493ac52655ad60698e05563870a846
runtime-tag=rust-v0.166.0
46 changes: 46 additions & 0 deletions agent/test/codex-pins-sync.test.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
import { it } from "node:test";
import assert from "node:assert/strict";
import { spawnSync } from "node:child_process";
import { createHash } from "node:crypto";
import { copyFileSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readlinkSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { dirname, join } from "node:path";
Expand Down Expand Up @@ -172,3 +173,48 @@ it("syncs the small tree and is idempotent", () => {
rmSync(dir, { recursive: true, force: true });
}
});

it("never rewrites a recorded adoption assertion, even malformed text containing a live pin", () => {
const file = "agent/codex/codex-package.adopted";
// Even an invalid assertion is not sync's to repair or re-certify.
for (const suffix of ["", `binary at ${INSTALL_ROOT}${current.version}/bin/codex\n`]) {
const assertion = `lock-sha256=${"a".repeat(64)}\nruntime-tag=rust-v${current.version}\n${suffix}`;
const dir = smallTree((files) => { files[LOCK] = bumped(realLock); files[file] = assertion; });
try {
assert.ok(!scannedPinFiles(dir).includes(file), "adoption is excluded from live-pin discovery");
assert.ok(!syncCodexPins(dir).includes(file));
assert.equal(readFileSync(join(dir, file), "utf8"), assertion, "sync does not certify adoption");
} finally {
rmSync(dir, { recursive: true, force: true });
}
}
});

it("a synchronized runtime bump still fails the release adoption guard until hand-recorded", () => {
const file = "agent/codex/codex-package.adopted";
const assertion = `lock-sha256=${createHash("sha256").update(realLock).digest("hex")}\nruntime-tag=rust-v${current.version}\n`;
const cutter = readFileSync(join(root, ".agents/skills/uzi-release/scripts/release-cut.sh"), "utf8");
// Exercise the real planner guard without the unrelated release ceremony.
const start = cutter.indexOf("codex_adoption_record_matches() {");
const end = cutter.indexOf("\n}\n", start);
assert.ok(start >= 0 && end > start);
const guard = `${cutter.slice(start, end + 3)}\ncodex_adoption_record_matches HEAD\n`;
const dir = smallTree((files) => { files[file] = assertion; });
const commit = () => { git(dir, "add", "-A"); git(dir, "-c", "user.name=Fixture", "-c", "user.email=fixture@example.test", "commit", "-qm", "fixture"); };
const check = () => spawnSync("bash", ["-s"], { cwd: dir, input: guard, encoding: "utf8" });
try {
commit();
assert.equal(check().status, 0, "the original committed assertion authorizes its lock");
writeFileSync(join(dir, LOCK), bumped(realLock));
syncCodexPins(dir);
assert.equal(readFileSync(join(dir, file), "utf8"), assertion);
commit();
assert.equal(check().status, 1, "pin sync cannot authorize the bumped runtime for nightly release");
const nextLock = readFileSync(join(dir, LOCK));
writeFileSync(join(dir, file), `lock-sha256=${createHash("sha256").update(nextLock).digest("hex")}\nruntime-tag=rust-v${NEXT.version}\n`);
commit();
assert.equal(check().status, 0, "the explicit adoption update authorizes the new lock");
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
2 changes: 2 additions & 0 deletions agent/test/codex-pins.ts
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,8 @@ const PIN_SCAN_EXCLUDES = [
":(exclude)e2e/worker-uid/issue-2397-investigation.md",
// A recorded frame tape is historical evidence, not a live deployment pin.
":(exclude)agent/test/fixtures/codex-plan-output-schema-0.164.0.json",
// A maintainer's adoption assertion must never be certified by pin sync.
":(exclude)agent/codex/codex-package.adopted",
// Synthetic version output deliberately includes mismatches to test the verifier.
":(exclude)e2e/codex-m4/provision.test.ts",
];
Expand Down
Loading
Loading