chore(release): prepare @aictrl/cli 0.4.8

[byapparov]

Version bump for 0.4.8, following RELEASING.md.

• packages/cli/package.json and the packages/cli workspace entry in bun.lock go to 0.4.8. bun install --frozen-lockfile passes.
• RELEASING.md: the 0.4.8 candidate notes replace the 0.4.7 section, and step 1 now includes cutting the CHANGELOG.
• CHANGELOG.md: Unreleased is cut. The breaking change goes under 0.4.8, and older entries move under the releases that shipped them (0.4.4, 0.4.3, 0.4.1).
• Release regressions plus the output-schema session, CLI and prompt-loop suites: 216 pass, 0 fail.

What 0.4.8 ships (#142, closes #140):

• BREAKING for --output-schema callers: StructuredOutput takes only { "path": "<file>" }.
  • The model writes its result as JSON to a file in the working directory and passes the path.
  • The CLI validates that file and publishes it; result objects passed as tool arguments are rejected.
• Only { path } reaches the provider, so provider schema conversion can no longer drop result fields. On 0.4.7, Gemini emptied map-typed fields (StructuredOutput drops additionalProperties (map) fields on Gemini; Ajv accepts the lossy {} #139).
• Hardened file reads:
  • containment inside the working directory, including symlink-swap races (post-open inode re-check, plus O_NOFOLLOW where defined);
  • FIFOs are rejected without blocking;
  • reads are bounded at 2 MiB;
  • every failure is a fixed, counted diagnostic.
• The prose-only missing diagnostic and reminder use the file form.

Why a patch bump: schema mode is used only by the aictrl executor, which pins exact versions. Consumers on a caret range (^0.4.x) must update their schema-mode prompts to the file+path form before upgrading.

Evidence (#139 reproduction):

• 0.4.7: Gemini 3.8 Flash published elements: {} 7/7.
• feat(run): StructuredOutput publishes the validated result file (#140) #142 builds: Gemini 10/10 and GLM 4/4 published all 6 keys identically.
• Gemini output + reasoning tokens fell from 2.5–3.9k to 1.0–1.8k.

After merge:

• gh release create v0.4.8 --target <merge SHA>, then the publish workflow and an install check.
• Then one aictrl PR that bumps the executor pin and, in the same PR, updates the prompts that ask for the result as tool arguments: prompt-builder.ts, pr-explanation-output-contract.ts and the explain-change skill.

🤖 Generated with Claude Code

https://claude.ai/code/session_019gASjVHuvN9AxK5WT8jzsN

[aictrl-dev]

🟠 Breaking change shipped as patch bump 0.4.8.

🤖 Fix with your agent

Fix this code review finding (aictrl-dev/cli PR #143, packages/cli/package.json:3):

Problem: Breaking change shipped as patch bump 0.4.8
Detail: RELEASING.md's new 0.4.8 section (line 39) explicitly labels the StructuredOutput contract change "**BREAKING for `--output-schema` callers (#142, closes #140)**" — the tool now accepts only `{ "path": "<file>" }` and result objects passed as tool arguments are rejected — yet the manifest bump is 0.4.7→0.4.8 (package.json and the bun.lock workspace entry). npm/bun caret ranges `^0.4.x` resolve to `<0.5.0`, so existing consumers auto-receive 0.4.8 on any routine update and their previously-working `--output-schema` prompts start failing with `structured_output_rejected`. The repo's own changelog precedent uses a minor bump for a feature/breaking batch (0.2.0) and patches for fixes (0.3.x). Semver's major-zero allowance technically permits this, but the release notes' own "callers must change prompts" makes the user impact concrete, so the version choice should be deliberate — either 0.5.0, or an explicit note that a patch bump was chosen because consumers pin exact versions.
Suggested fix: Bump to 0.5.0 in packages/cli/package.json and the matching bun.lock workspace entry and retitle the RELEASING.md section to "## 0.5.0 candidate"; alternatively keep 0.4.8 but state in RELEASING.md why a labeled breaking change ships as a patch (e.g. consumers are expected to pin exact versions), or accept the legacy result-object shape with a deprecation diagnostic for one release before rejecting it.

Implement the fix on the PR head branch and add a regression test that fails before the fix and passes after.

Why this matters

RELEASING.md's new 0.4.8 section (line 39) explicitly labels the StructuredOutput contract change "BREAKING for --output-schema callers (#142, closes #140)" — the tool now accepts only { "path": "<file>" } and result objects passed as tool arguments are rejected — yet the manifest bump is 0.4.7→0.4.8 (package.json and the bun.lock workspace entry). npm/bun caret ranges ^0.4.x resolve to <0.5.0, so existing consumers auto-receive 0.4.8 on any routine update and their previously-working --output-schema prompts start failing with structured_output_rejected. The repo's own changelog precedent uses a minor bump for a feature/breaking batch (0.2.0) and patches for fixes (0.3.x). Semver's major-zero allowance technically permits this, but the release notes' own "callers must change prompts" makes the user impact concrete, so the version choice should be deliberate — either 0.5.0, or an explicit note that a patch bump was chosen because consumers pin exact versions.

{
  "$schema": "https://json.schemastore.org/package.json",
  "version": "0.4.8",
  "name": "@aictrl/cli",
  "description": "Headless execution engine for AI agent skills",
  "type": "module",

[aictrl-dev]

Code review

Verdict: Address the major findings before merging. · 🔴 0 · 🟠 1 · 🟡 1 · ⚪ 0 · 0/2 resolved

• 🟡 CHANGELOG.md:3 — CHANGELOG Unreleased not cut for 0.4.8
• 🟠 packages/cli/package.json:3 — Breaking change shipped as patch bump 0.4.8

🤖 Fix all 2 open findings with your agent

Fix the following code review findings on aictrl-dev/cli PR #143 (head branch).
Run the relevant tests/linters after each change.

1. CHANGELOG.md:3 — CHANGELOG Unreleased not cut for 0.4.8
   Detail: This release-prep PR stamps 0.4.8 in package.json/bun.lock but leaves CHANGELOG.md's "## Unreleased" section (which already contains the 0.4.8 breaking-change entry) unversioned, even though the changelog's established format versions each release ("## 0.3.2 (2026-04-11)", "## 0.3.1", "## 0.2.0"). The newest versioned section is 0.3.2 while the package ships 0.4.8, so the drift grows with every release. Note RELEASING.md step 1 only mandates the version bump and bun.lock entry, so cutting the changelog may happen elsewhere — but nothing in the documented publish flow (steps 3–5) does it either.
   Suggested fix: In the release PR, retitle CHANGELOG.md's "## Unreleased" to "## 0.4.8 (<date>)" (folding or backfilling the stale 0.4.x entries), and add the changelog cut to RELEASING.md step 1 so the manifest version and changelog stay aligned.
2. packages/cli/package.json:3 — Breaking change shipped as patch bump 0.4.8
   Detail: RELEASING.md's new 0.4.8 section (line 39) explicitly labels the StructuredOutput contract change "**BREAKING for `--output-schema` callers (#142, closes #140)**" — the tool now accepts only `{ "path": "<file>" }` and result objects passed as tool arguments are rejected — yet the manifest bump is 0.4.7→0.4.8 (package.json and the bun.lock workspace entry). npm/bun caret ranges `^0.4.x` resolve to `<0.5.0`, so existing consumers auto-receive 0.4.8 on any routine update and their previously-working `--output-schema` prompts start failing with `structured_output_rejected`. The repo's own changelog precedent uses a minor bump for a feature/breaking batch (0.2.0) and patches for fixes (0.3.x). Semver's major-zero allowance technically permits this, but the release notes' own "callers must change prompts" makes the user impact concrete, so the version choice should be deliberate — either 0.5.0, or an explicit note that a patch bump was chosen because consumers pin exact versions.
   Suggested fix: Bump to 0.5.0 in packages/cli/package.json and the matching bun.lock workspace entry and retitle the RELEASING.md section to "## 0.5.0 candidate"; alternatively keep 0.4.8 but state in RELEASING.md why a labeled breaking change ships as a patch (e.g. consumers are expected to pin exact versions), or accept the legacy result-object shape with a deprecation diagnostic for one release before rejecting it.

📋 Out-of-diff findings (2)

Sev	Location	Finding
🟡	CHANGELOG.md:3	CHANGELOG Unreleased not cut for 0.4.8
🟠	packages/cli/package.json:3	Breaking change shipped as patch bump 0.4.8

Reviewed 3 files · 0 inline · view all 2 findings ↗

---

aictrl · AI code review for fast-moving teams · aictrl.dev

[byapparov]

Review response — PR #143

Both findings verified TRUE. The CHANGELOG one is fixed. On the version, the founder decided to keep 0.4.8, and the reason is now documented.

Issues addressed (pushed to this PR)

• CHANGELOG Unreleased not cut for 0.4.8 — CHANGELOG.md: Unreleased is cut. The breaking change goes under 0.4.8 (2026-10-10). The older entries move under the releases that actually shipped them, found with git tag --contains: 0.4.4 (provider error finishes), 0.4.3 (GPT-5.6, GLM-5.3) and 0.4.1 (NDJSON terminal reasons). There is a pointer to GitHub Releases for the rest. RELEASING.md step 1 now includes the CHANGELOG cut. (commit 55efa9197b)

Review claims verified false (no change needed)

None.

Not addressed here

• Breaking change shipped as patch bump 0.4.8 — The claim is correct: ^0.4.x resolves to <0.5.0, so 0.4.8 reaches caret-range consumers. The founder decided to keep 0.4.8. Schema mode is used only by the aictrl executor, which pins exact versions. RELEASING.md, CHANGELOG.md and the release notes now say so, and that caret-range consumers must update their schema-mode prompts to the file+path form before upgrading (commit 55efa9197b). No version change.

[aictrl-dev]

⚪ Changelog pointer range spans never-published 0.4.2.

🤖 Fix with your agent

Fix this code review finding (aictrl-dev/cli PR #143, CHANGELOG.md:28):

Problem: Changelog pointer range spans never-published 0.4.2
Detail: The new pointer line is accurate for every release that actually shipped (verified via read-only GitHub API: all unlisted versions in range — 0.3.3, 0.3.4, 0.3.5, 0.3.6, 0.3.7, 0.4.0, 0.4.5, 0.4.6, 0.4.7 — have GitHub Releases, and the retroactively added dates for 0.4.4/0.4.3/0.4.1 match their publish dates). However, the stated range 0.3.3–0.4.7 spans a gap: version 0.4.2 was never published at all — it is absent from npm (`npm view @aictrl/cli versions` jumps 0.4.1 → 0.4.3), from git tags, and from GitHub Releases (`releases/tags/v0.4.2` → 404). A reader who assumes contiguous releases may hunt for 0.4.2 notes via this pointer and find nothing. A short parenthetical noting the skip would preempt that confusion; purely optional since the sentence makes no false claim about any existing release.
Suggested fix: Optionally exclude the skipped version, e.g. "Releases 0.3.3–0.4.7 not listed here (0.4.2 was never published) have notes on [GitHub Releases](https://github.com/aictrl-dev/cli/releases) only."

Implement the fix on the PR head branch and add a regression test that fails before the fix and passes after.

Why this matters

The new pointer line is accurate for every release that actually shipped (verified via read-only GitHub API: all unlisted versions in range — 0.3.3, 0.3.4, 0.3.5, 0.3.6, 0.3.7, 0.4.0, 0.4.5, 0.4.6, 0.4.7 — have GitHub Releases, and the retroactively added dates for 0.4.4/0.4.3/0.4.1 match their publish dates). However, the stated range 0.3.3–0.4.7 spans a gap: version 0.4.2 was never published at all — it is absent from npm (npm view @aictrl/cli versions jumps 0.4.1 → 0.4.3), from git tags, and from GitHub Releases (releases/tags/v0.4.2 → 404). A reader who assumes contiguous releases may hunt for 0.4.2 notes via this pointer and find nothing. A short parenthetical noting the skip would preempt that confusion; purely optional since the sentence makes no false claim about any existing release.

- **NDJSON v1 terminal reasons are an open set** — `session_error.reason` now includes `interrupted` for `SIGINT` and `terminated` for `SIGTERM`, and `code` may contain the conventional signal-derived exit code (`130` or `143`). Schema v1 consumers should treat unknown event types, fields, and enum-like string values as forward-compatible additions.

Releases 0.3.3–0.4.7 not listed here have notes on [GitHub Releases](https://github.com/aictrl-dev/cli/releases) only.

## 0.3.2 (2026-04-11)

[aictrl-dev]

Code review

Verdict: Looks good — only minor / nit comments below. · 🔴 0 · 🟠 0 · 🟡 0 · ⚪ 1 · 0/1 resolved

• ⚪ CHANGELOG.md:28 — Changelog pointer range spans never-published 0.4.2

🤖 Fix all 1 open findings with your agent

Fix the following code review findings on aictrl-dev/cli PR #143 (head branch).
Run the relevant tests/linters after each change.

1. CHANGELOG.md:28 — Changelog pointer range spans never-published 0.4.2
   Detail: The new pointer line is accurate for every release that actually shipped (verified via read-only GitHub API: all unlisted versions in range — 0.3.3, 0.3.4, 0.3.5, 0.3.6, 0.3.7, 0.4.0, 0.4.5, 0.4.6, 0.4.7 — have GitHub Releases, and the retroactively added dates for 0.4.4/0.4.3/0.4.1 match their publish dates). However, the stated range 0.3.3–0.4.7 spans a gap: version 0.4.2 was never published at all — it is absent from npm (`npm view @aictrl/cli versions` jumps 0.4.1 → 0.4.3), from git tags, and from GitHub Releases (`releases/tags/v0.4.2` → 404). A reader who assumes contiguous releases may hunt for 0.4.2 notes via this pointer and find nothing. A short parenthetical noting the skip would preempt that confusion; purely optional since the sentence makes no false claim about any existing release.
   Suggested fix: Optionally exclude the skipped version, e.g. "Releases 0.3.3–0.4.7 not listed here (0.4.2 was never published) have notes on [GitHub Releases](https://github.com/aictrl-dev/cli/releases) only."

📋 Out-of-diff findings (1)

Sev	Location	Finding
⚪	CHANGELOG.md:28	Changelog pointer range spans never-published 0.4.2

Reviewed 4 files · 0 inline · view all 1 findings ↗

---

aictrl · AI code review for fast-moving teams · aictrl.dev

[byapparov]

Review response — PR #143 (second review)

The single ⚪ finding was verified TRUE and fixed.

Issues addressed (pushed to this PR)

• Changelog pointer range spans never-published 0.4.2 — CHANGELOG.md: the pointer now says "(0.4.2 was never published)". git tag -l v0.4.2 is empty, and npm versions go from 0.4.1 straight to 0.4.3. (commit bf3f9afce0)

Review claims verified false (no change needed)

None.

Not addressed here

None.