@ikon85/agent-workflow-kit 0.27.1 → 0.29.0

package/docs/research/wave-152-consumer-acceptance.md

@@ -0,0 +1,98 @@
+# Wave 152 consumer acceptance and release checklist
+
+Verified on 2026-07-19 for candidate `52ea49856a03f6e4bb13f24913990769126f81a8`.
+
+## Candidate
+
+- Source repository: `iKon85/agent-workflow-kit`
+- Candidate tarball: `/tmp/wave152-final-candidate.8CRnlP/ikon85-agent-workflow-kit-0.28.0.tgz`
+- Extracted kit: `/tmp/wave152-final-package.QQTOvE/package/dist-kit`
+- Disposable consumer checkout: `/tmp/wave152-testreporter.ZZg8zY/checkout`
+- Consumer base: `iKon85/Testreporter` `origin/main` at
+  `76bcaa91`
+
+The temporary paths record the exact acceptance input. They are not release
+artifacts; a repeat run creates fresh temporary directories and a fresh
+test-only marker identity.
+
+## Repeatable procedure
+
+1. Build the kit from the candidate commit, create an npm tarball, extract it,
+   and run its `kit:build`. Install that built kit into a disposable checkout
+   of the consumer's current `origin/main`.
+2. Run `scripts/codex-exec.sh new` with the `review` profile and `read-only`
+   mode. Capture the opaque run ID, resume it for round 2, verify both rounds
+   return `OK`, then finalize and verify that the run state is deleted.
+3. Run `scripts/codex-exec.sh new` with the `build` profile and
+   `workspace-write` mode. Ask it to create only an allowlisted ignored scratch
+   file containing a fixed sentinel, verify the sentinel, finalize the run,
+   and remove the scratch file.
+4. Create a disposable consumer issue through `scripts/board-sync.py` with a
+   unique `wave-stub-source` marker. Resolve it through
+   `scripts/find-by-marker.py`, verify one exact match, move its board status to
+   Done, close it, and repeat the lookup. The terminal lookup must report the
+   closed/user-decision branch and an all-open scan must find zero disposable
+   issues.
+
+## Acceptance evidence
+
+| Smoke | Evidence | Result |
+|---|---|---|
+| `codex-review` read-only | Real new round returned `OK` with a thread; resume round 2 returned `OK`; finalize deleted run state. | PASS |
+| `codex-build` workspace-write | Created only ignored `_ai_temp/wave152-build-smoke.txt` with `WAVE152_BUILD_SMOKE_OK`; finalize succeeded; scratch file removed. | PASS |
+| Marker roundtrip | Identity `wave-stub-source=awkit-wave152-20260719-acceptance-52ea498` created Testreporter issue #2168 through board-sync; exact lookup was unique; board status became Done; issue was closed; final lookup selected closed/user-decision; `openDisposable=0`. | PASS |
+
+No open disposable issue or scratch file remained after acceptance. The closed
+issue remains deliberate cleanup evidence and is excluded from open productive
+work by the all-state lookup's closed/user-decision result.
+
+## Counted surface census: 31 of 31
+
+The denominator is re-derived from the current skill manifest and the delivery
+surfaces, not from the changed-file list.
+
+| Surface class | Derivation | Covered |
+|---|---|---:|
+| Skill surfaces | Nine records from `.claude/skills/skill-manifest.json`: four Claude-only Codex skills (4), three dual-surface marker callers (6), dual-surface `to-issues` (2), and dual-surface `wrapup` (2). The four Codex skills intentionally have no invented `.agents` mirrors. | 14/14 |
+| Bundle registrations | The five Wave helpers in `HELPER_FILES`, with their declared kind and mode. | 5/5 |
+| Checked manifest entries | The same five helpers in the freshly built and checked `agent-workflow-kit.package.json`. | 5/5 |
+| Test surfaces | Harness scenarios, thin-skill lifecycle, marker library/CLI, anchor renderer/promotion, wrapup contradiction absence, and bundle/manifest/tarball modes. | 6/6 |
+| Shared board callsite | `scripts/board-sync.py` imports and uses the shared marker parser instead of retaining a second grammar. | 1/1 |
+| **Total** | **No unexplained gap.** | **31/31** |
+
+The exact manifest-derived skill set is:
+
+- Claude-only: `codex-review`, `codex-build`, `grill-me-codex`,
+  `grill-with-docs-codex`.
+- Dual-surface: `to-prd`, `to-waves`, `board-to-waves`, `to-issues`, `wrapup`.
+
+The five helper modes are:
+
+- `scripts/marker_lib.py` — `0644`
+- `scripts/find-by-marker.py` — `0755`
+- `scripts/codex-exec.sh` — `0755`
+- `scripts/codex_proc.py` — `0644`
+- `scripts/render-anchor.py` — `0755`
+
+## Release checklist
+
+- [x] K1-K5 integrated into one candidate.
+- [x] K1, K2, and K4 passed independent Standards and Spec reviews.
+- [x] Candidate tarball passed all three real consumer smokes.
+- [x] Disposable consumer issue and scratch file cleaned up; no open disposable
+      issue remains.
+- [x] Bundle, built-manifest, and npm-tarball mode assertions cover all five
+      helpers.
+- [x] Surface census is 31 of 31 with zero unexplained gaps.
+- [x] Prepared the user-authorized single minor bump from 0.28.0 to 0.29.0 and
+      refresh checked release state.
+- [x] `release:prepare -- --version 0.29.0` completed its release guard, full
+      test suite, manifest rebuild, and dry-run npm pack.
+- [x] Re-ran the full suite (354 Node tests and 277 Python tests),
+      `kit:staleness` (`OK`), and `release:guard` (`OK (minor)`).
+- [x] Created and extracted the final `0.29.0` npm tarball (380 package
+      entries); all five helper modes matched both pack metadata and extracted
+      filesystem modes.
+- [ ] After merge, let the trusted release workflow publish and verify
+      `npm run release:status` reports `released` before declaring the release
+      complete.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikon85/agent-workflow-kit",
-  "version": "0.27.1",
+  "version": "0.29.0",
   "description": "Portable AI-agent workflow skills (plan → execute → land → learn) for Claude Code & Codex — grilling, TDD, diagnosis, two-axis code review, cross-model Codex review, design & domain-modeling, plus a skill router (ask-matt). npx init/update/diff/uninstall.",
   "type": "module",
   "bin": {

package/scripts/board-sync.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 """board-sync.py — single GitHub Projects-v2 board-sync / sub-issue helper.
 
-Encapsulates the five board mechanics the planning skills used to inline as bare
+Encapsulates the board mechanics the planning skills used to inline as bare
 `gh` snippets (board-to-waves, to-prd, to-issues):
 
   1. GraphQL-Link    — native parent↔child sub-issue link (`link`)
@@ -9,6 +9,10 @@ Encapsulates the five board mechanics the planning skills used to inline as bare
   3. preview-header  — `GraphQL-Features: sub_issues` on every sub-issue call
   4. Wave-Stempel    — stamp the Wave (number) field (`--wave` on `create`/`add`)
   5. board-sync      — add an issue to the board + set Status/Wave/Cluster/Path fields
+  6. next-wave       — rate-efficient title search with a bounded full-scan fallback
+  7. promotion guard — reject a Wave number already held by another anchor
+  8. item-of         — targeted item/field lookup without scanning the whole board
+  9. archive-done    — dry-run-first, bounded-batch archival of active Done items
 
 Board-specific values (field IDs, status names, labels) are NOT inlined here —
 board_config reads them from the `board-sync:profile` block in
@@ -49,6 +53,7 @@ from node_kind import classify_node, PROGRAM  # noqa: E402
 # "open blocker" predicate, shared with the execute-ready drift check;
 # native dependencies (API) are the truth.
 from issue_deps import open_blocker_numbers, splice_blocked_by_section  # noqa: E402
+from marker_lib import first_marker  # noqa: E402
 
 # --- Board profile (SSOT: docs/agents/board-sync.md `board-sync:profile`) ----
 # No inline board IDs: board_config reads them from the profile so the published
@@ -95,6 +100,8 @@ def _status_roles_or_hint(context: str) -> dict:
     return STATUS_ROLES
 PROJECT_ITEM_LIST_LIMIT = 2000
 GH_TIMEOUT_SECONDS = 15  # a hanging gh prompt must not block a session indefinitely
+PROJECT_ITEM_LIST_TIMEOUT_SECONDS = 60  # full-board reads are slower, but still bounded
+ARCHIVE_DONE_BATCH_SIZE = 30
 
 # Sub-issues GraphQL API is behind a preview feature gate per account.
 SUB_ISSUES_HEADER = "GraphQL-Features: sub_issues"
@@ -127,11 +134,13 @@ class GhError(RuntimeError):
 # --- subprocess seam (the only thing tests monkeypatch) ----------------------
 def _gh(args: list[str]) -> str:
     """Run `gh <args>`, return stdout. Raise GhError on non-zero exit or timeout."""
+    timeout = (PROJECT_ITEM_LIST_TIMEOUT_SECONDS
+               if args[:2] == ["project", "item-list"] else GH_TIMEOUT_SECONDS)
     try:
         result = subprocess.run(["gh", *args], capture_output=True, text=True,
-                                 timeout=GH_TIMEOUT_SECONDS)
+                                 timeout=timeout)
     except subprocess.TimeoutExpired as exc:
-        raise GhError(f"gh {' '.join(args)} timed out after {GH_TIMEOUT_SECONDS}s") from exc
+        raise GhError(f"gh {' '.join(args)} timed out after {timeout}s") from exc
     if result.returncode != 0:
         # `gh api graphql` exits non-zero when the response body carries GraphQL
         # `errors` even alongside a partial `data` (stamp-batch's per-alias
@@ -154,15 +163,10 @@ def _print_dry(args: list[str]) -> None:
 
 
 # --- pure logic (directly unit-tested) ---------------------------------------
-_PROGRAM_CREATE_IDENTITY_RE = re.compile(
-    r"<!--\s*(program-(?:stub|leaf)-source):\s*([^>]+?)\s*-->"
-)
-
-
 def extract_program_create_identity(body: str) -> Optional[str]:
     """Stable to-waves identity carried by a stub/leaf body, if present."""
-    match = _PROGRAM_CREATE_IDENTITY_RE.search(body)
-    return f"{match.group(1)}: {match.group(2).strip()}" if match else None
+    marker = first_marker(body, ("program-stub-source", "program-leaf-source"))
+    return f"{marker[0]}: {marker[1]}" if marker else None
 
 
 def _find_open_issue_by_program_identity(body: str) -> Optional[dict]:
@@ -422,6 +426,10 @@ WAVE_TITLE_PREFIX = wave_title_prefix(_CFG)
 _WAVE_PREFIX_RE = re.compile(
     rf"^\s*{re.escape(WAVE_TITLE_PREFIX)}\s+\d+\s*[—–-]\s*", re.IGNORECASE
 )
+_WAVE_NUMBER_RE = re.compile(rf"^{re.escape(WAVE_TITLE_PREFIX)}\s+(\d+)\b")
+_ANCHOR_TITLE_RE = re.compile(
+    rf"^{re.escape(WAVE_TITLE_PREFIX)}\s+(\d+)\s+—\s+"
+)
 # Leading conventional-commit token (`fix:`, `feat(ui):`, `chore!:`) — anchors
 # don't carry these, so strip it when present. Matches only a lowercase token,
 # so prose titles like "Supabase-Residuen entfernen: …" are left intact.
@@ -443,6 +451,26 @@ def wave_title(current: str, wave: int) -> str:
     return f"{WAVE_TITLE_PREFIX} {wave} — {thema}"
 
 
+def compute_next_wave_from_search(payload: dict) -> Optional[int]:
+    """Return max wave-title number + 1, or None so callers can full-scan."""
+    numbers = []
+    for item in payload.get("items", []):
+        match = _WAVE_NUMBER_RE.match(item.get("title") or "")
+        if match:
+            numbers.append(int(match.group(1)))
+    return max(numbers) + 1 if numbers else None
+
+
+def wave_collision_guard(payload: dict, wave: int, issue: int) -> Optional[str]:
+    """Reject a wave number carried by another anchor; allow replay and leaves."""
+    for item in payload.get("items", []):
+        match = _ANCHOR_TITLE_RE.match(item.get("title") or "")
+        if match and int(match.group(1)) == wave and item.get("number") != issue:
+            return (f"Wave {wave} is already taken by #{item.get('number')} "
+                    f"({item.get('title')!r}); re-read `next-wave` and retry")
+    return None
+
+
 def title_edit_args(issue: int, title: str) -> list[str]:
     """The `gh issue edit` argv that sets an issue's title."""
     return ["issue", "edit", str(issue), "--repo", REPO, "--title", title]
@@ -511,6 +539,43 @@ def _field_value(issue: int, field_id: str) -> Optional[dict]:
     return extract_field_value(data, PROJECT_NODE_ID, field_id)
 
 
+def extract_item_overview(data: dict, project_node_id: str, field_ids: dict) -> Optional[dict]:
+    """Extract one issue's item id and configured field values for this project."""
+    issue = (data.get("data") or {}).get("repository", {}).get("issue") or {}
+    for node in (issue.get("projectItems") or {}).get("nodes") or []:
+        if (node.get("project") or {}).get("id") != project_node_id:
+            continue
+        by_field = {(value.get("field") or {}).get("id"): value
+                    for value in (node.get("fieldValues") or {}).get("nodes") or []}
+        overview = {"itemId": node.get("id")}
+        for name, field_id in field_ids.items():
+            value = by_field.get(field_id)
+            if value is None:
+                overview[name] = None
+            elif "number" in value:
+                overview[name] = value["number"]
+            elif "name" in value:
+                overview[name] = value["name"]
+            else:
+                overview[name] = value.get("text")
+        return overview
+    return None
+
+
+def cmd_item_of(args) -> int:
+    data = _gh_json(["api", "graphql", "-f", f"query={FIELD_VALUE_QUERY}",
+                     "-F", f"owner={PROJECT_OWNER}", "-F", f"repo={REPO_NAME}",
+                     "-F", f"num={args.issue}"])
+    overview = extract_item_overview(data, PROJECT_NODE_ID, {
+        "wave": WAVE_FIELD_ID, "status": STATUS_FIELD_ID, "cluster": CLUSTER_FIELD_ID,
+    })
+    if overview is None:
+        print("NOT-ON-BOARD")
+        return 1
+    print(json.dumps(overview, ensure_ascii=False))
+    return 0
+
+
 def _write_issue_body(issue: int, new_body: str) -> None:
     """Write an issue body via a temp file + `gh issue edit --body-file` — the
     one shared write mechanic for every body-rewriting command in this file."""
@@ -534,13 +599,101 @@ def _add_and_stamp(url, wave, status, cluster, spec_path, plan_path, dry_run) ->
 
 
 # --- commands ----------------------------------------------------------------
-def cmd_next_wave(_args) -> int:
+def cmd_next_wave(args) -> int:
+    if not getattr(args, "scan", False):
+        payload = _gh_json(["api", "-X", "GET", "search/issues",
+                            "-f", f'q=repo:{REPO} is:issue in:title "{WAVE_TITLE_PREFIX}"',
+                            "-f", "per_page=100", "-f", "sort=created", "-f", "order=desc"])
+        next_wave = compute_next_wave_from_search(payload)
+        if next_wave is not None:
+            print(next_wave)
+            return 0
+        print(f"hint: title search found no '{WAVE_TITLE_PREFIX} <N>' issue; "
+              "falling back to the full board scan", file=sys.stderr)
     items = _gh_json(["project", "item-list", str(PROJECT_NUMBER), "--owner", PROJECT_OWNER,
                       "--limit", str(PROJECT_ITEM_LIST_LIMIT), "--format", "json"]).get("items", [])
     print(compute_next_wave(items))
     return 0
 
 
+def extract_done_items(items: list[dict], done_status: str) -> list[dict]:
+    return [item for item in items
+            if item.get("id") and item.get("status") == done_status
+            and not item.get("archived", False) and not item.get("isArchived", False)]
+
+
+def build_archive_mutation(item_ids: list[str]) -> str:
+    calls = []
+    for index, item_id in enumerate(item_ids):
+        calls.append(
+            f"a{index}: archiveProjectV2Item(input: "
+            f"{{projectId: {json.dumps(PROJECT_NODE_ID)}, itemId: {json.dumps(item_id)}}}) "
+            "{ item { id } }"
+        )
+    return "mutation { " + " ".join(calls) + " }"
+
+
+def parse_archive_response(response: dict, item_ids: list[str]) -> tuple[list[str], list[tuple[str, str]]]:
+    data = response.get("data") or {}
+    errors = {error["path"][0]: error.get("message", "unknown GraphQL error")
+              for error in response.get("errors") or [] if error.get("path")}
+    global_errors = [error.get("message", "unknown GraphQL error")
+                     for error in response.get("errors") or [] if not error.get("path")]
+    fallback = "; ".join(global_errors) or "no successful response"
+    succeeded, failed = [], []
+    for index, item_id in enumerate(item_ids):
+        alias = f"a{index}"
+        if data.get(alias) and data[alias].get("item"):
+            succeeded.append(item_id)
+        else:
+            failed.append((item_id, errors.get(alias, fallback)))
+    return succeeded, failed
+
+
+def cmd_archive_done(args) -> int:
+    done_status = resolve_status_role("done", _status_roles_or_hint("archive-done"))
+    payload = _gh_json(["project", "item-list", str(PROJECT_NUMBER),
+                        "--owner", PROJECT_OWNER, "--limit", str(PROJECT_ITEM_LIST_LIMIT),
+                        "--format", "json", "--jq",
+                        "{items: [.items[] | {id, status, archived, isArchived}], "
+                        "totalCount: .totalCount}"])
+    items = payload.get("items", [])
+    total_count = payload.get("totalCount", len(items))
+    if total_count > len(items):
+        raise ValueError(f"project item-list returned {len(items)} of {total_count} items; "
+                         "refusing a partial archive")
+    done_items = extract_done_items(items, done_status)
+    print(f"archive-done: {len(done_items)} of {total_count} active items have status {done_status}")
+    if not done_items:
+        print("archive-done: nothing to archive (idempotent)")
+        return 0
+    chunks = [done_items[start:start + ARCHIVE_DONE_BATCH_SIZE]
+              for start in range(0, len(done_items), ARCHIVE_DONE_BATCH_SIZE)]
+    if not args.apply:
+        for chunk in chunks:
+            _print_dry(["api", "graphql", "-f",
+                        f"query={build_archive_mutation([item['id'] for item in chunk])}"])
+        print("archive-done: dry-run only; pass --apply to archive")
+        return 0
+    succeeded, failed = [], []
+    for chunk in chunks:
+        item_ids = [item["id"] for item in chunk]
+        query = build_archive_mutation(item_ids)
+        try:
+            output = _gh(["api", "graphql", "-f", f"query={query}"])
+        except GhError as exc:
+            output = getattr(exc, "stdout", "") or ""
+            if not output:
+                raise
+        batch_succeeded, batch_failed = parse_archive_response(json.loads(output), item_ids)
+        succeeded += batch_succeeded
+        failed += batch_failed
+    print(f"archive-done: {len(succeeded)} of {len(done_items)} Done items archived")
+    for item_id, message in failed:
+        print(f"  ERROR {item_id}: {message}")
+    return 1 if failed else 0
+
+
 def cmd_parent_of(args) -> int:
     parent = _parent_of(args.issue)
     print(parent if parent is not None else "FREI")
@@ -793,6 +946,13 @@ def cmd_promote(args) -> int:
     if mismatch:
         print(f"error: {mismatch}", file=sys.stderr)
         return 1
+    search = _gh_json(["api", "-X", "GET", "search/issues",
+                       "-f", f'q=repo:{REPO} is:issue in:title "{WAVE_TITLE_PREFIX} {args.wave}"',
+                       "-f", "per_page=100"])
+    collision = wave_collision_guard(search, args.wave, args.issue)
+    if collision:
+        print(f"error: {collision}", file=sys.stderr)
+        return 1
     done: list[str] = []
     try:
         strip = type_labels_to_strip(labels)
@@ -1089,7 +1249,22 @@ def build_parser() -> argparse.ArgumentParser:
     p = argparse.ArgumentParser(prog="board-sync.py", description=__doc__.splitlines()[0])
     sub = p.add_subparsers(dest="command", required=True)
 
-    sub.add_parser("next-wave", help="print the next monotone wave number").set_defaults(func=cmd_next_wave)
+    nw = sub.add_parser("next-wave", help="print the next monotone wave number "
+                                           "(cheap title search; --scan reads the full board)")
+    nw.add_argument("--scan", action="store_true")
+    nw.set_defaults(func=cmd_next_wave)
+
+    archive = sub.add_parser(
+        "archive-done",
+        help="preview archival of active Done items; --apply performs bounded batches",
+    )
+    archive.add_argument("--apply", action="store_true",
+                         help="perform archival (the default is a non-mutating dry-run)")
+    archive.set_defaults(func=cmd_archive_done)
+
+    item = sub.add_parser("item-of", help="targeted item id and field lookup for one issue")
+    item.add_argument("--issue", type=int, required=True)
+    item.set_defaults(func=cmd_item_of)
 
     po = sub.add_parser("parent-of", help="print an issue's parent number or FREI")
     po.add_argument("issue", type=int)

package/scripts/build-kit.test.mjs

@@ -1,6 +1,6 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
-import { access, mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { access, mkdir, mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -8,12 +8,20 @@ import { createHash } from 'node:crypto';
 import { execFileSync } from 'node:child_process';
 import { buildKit } from './build-kit.mjs';
 import { init } from '../src/commands/init.mjs';
+import { HELPER_FILES } from '../src/lib/bundle.mjs';
 import { CONSUMER_MANIFEST_NAME, readManifest } from '../src/lib/manifest.mjs';
 
 const REPO = join(dirname(fileURLToPath(import.meta.url)), '..');
 const PUBLIC_CENSUS_UNIT = JSON.parse(await readFile(
   join(REPO, 'test/fixtures/census-consumers/public-unit.json'), 'utf8',
 )).paths;
+const WAVE_152_HELPERS = [
+  { path: 'scripts/marker_lib.py', kind: 'script', mode: 0o644 },
+  { path: 'scripts/find-by-marker.py', kind: 'script', mode: 0o755 },
+  { path: 'scripts/codex-exec.sh', kind: 'script', mode: 0o755 },
+  { path: 'scripts/codex_proc.py', kind: 'script', mode: 0o644 },
+  { path: 'scripts/render-anchor.py', kind: 'script', mode: 0o755 },
+];
 async function withBuild(fn) {
   const dist = await mkdtemp(join(tmpdir(), 'awkit-build-'));
   try { return await fn(dist, await buildKit({ repoRoot: REPO, distDir: dist })); }
@@ -89,6 +97,24 @@ test('current build contains post-tag public files and repository metadata', asy
   });
 });
 
+test('Wave 152 helpers keep their bundle and built-manifest modes', async () => {
+  assert.deepEqual(
+    WAVE_152_HELPERS.map(({ path }) => HELPER_FILES.find((entry) => entry.path === path)),
+    WAVE_152_HELPERS,
+  );
+  await withBuild(async (dist) => {
+    const manifest = JSON.parse(await readFile(join(dist, 'agent-workflow-kit.package.json'), 'utf8'));
+    const byPath = new Map(manifest.files.map((entry) => [entry.path, entry]));
+    assert.deepEqual(
+      WAVE_152_HELPERS.map(({ path }) => {
+        const { kind, mode, installRole } = byPath.get(path);
+        return { path, kind, mode, installRole };
+      }),
+      WAVE_152_HELPERS.map((entry) => ({ ...entry, installRole: 'consumer' })),
+    );
+  });
+});
+
 test('current build contains the complete dual-surface census consumer unit', async () => {
   await withBuild(async (dist, report) => {
     const manifest = JSON.parse(await readFile(join(dist, 'agent-workflow-kit.package.json'), 'utf8'));
@@ -129,6 +155,11 @@ test('npm pack keeps product files but excludes runtime residue', async () => {
     for (const path of PUBLIC_CENSUS_UNIT) {
       assert.ok(files.includes(path), `pack missing ${path}`);
     }
+    const packedByPath = new Map(JSON.parse(output)[0].files.map((file) => [file.path, file]));
+    assert.deepEqual(
+      WAVE_152_HELPERS.map(({ path, mode }) => ({ path, mode: packedByPath.get(path)?.mode })),
+      WAVE_152_HELPERS.map(({ path, mode }) => ({ path, mode })),
+    );
     assert.ok(files.every((path) => !path.startsWith('.claude/logs/')));
     assert.ok(files.every((path) => !path.includes('__pycache__') && !path.endsWith('.pyc')));
     const pkg = JSON.parse(execFileSync('node', ['-p', 'JSON.stringify(require("./package.json"))'], {
@@ -147,6 +178,16 @@ test('packed scoped artifact keeps the existing npx default-bin inference', asyn
     const packed = JSON.parse(execFileSync('npm', [
       'pack', '--pack-destination', destination, '--json',
     ], { cwd: REPO, encoding: 'utf8' }));
+    const packedByPath = new Map(packed[0].files.map((file) => [file.path, file]));
+    execFileSync('tar', ['-xzf', join(destination, packed[0].filename), '-C', destination]);
+    for (const { path, mode } of WAVE_152_HELPERS) {
+      assert.equal(packedByPath.get(path)?.mode, mode, `packed mode mismatch: ${path}`);
+      assert.equal(
+        (await stat(join(destination, 'package', path))).mode & 0o777,
+        mode,
+        `extracted mode mismatch: ${path}`,
+      );
+    }
     const output = execFileSync('npx', [
       '--yes', '--offline', `./${packed[0].filename}`,
     ], { cwd: destination, encoding: 'utf8' });

package/scripts/codex-exec-scenarios/fake-codex.mjs

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+import { appendFileSync, writeFileSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+
+const args = process.argv.slice(2);
+const scenario = process.env.FAKE_CODEX_SCENARIO ?? 'ok';
+const pause = Number(process.env.FAKE_CODEX_PAUSE_MS ?? 1_000);
+
+if (args.includes('--version') || args[0] === '--version') {
+  console.log(`codex-cli ${process.env.FAKE_CODEX_VERSION ?? '0.144.6'}`);
+  process.exit(0);
+}
+if (args[0] === 'login' && args[1] === 'status') {
+  if (scenario === 'auth-fail') {
+    console.error('Not logged in');
+    process.exit(1);
+  }
+  console.log('Logged in using fake credentials');
+  process.exit(0);
+}
+if (args.includes('--help')) {
+  const resumeHelp = args[0] === 'exec' && args[1] === 'resume';
+  if (process.env.FAKE_CODEX_MISSING_CAPABILITY === '1'
+      || (resumeHelp && process.env.FAKE_CODEX_RESUME_MISSING_CAPABILITY === '1')) {
+    console.log('Usage: codex exec [PROMPT]');
+  } else if (resumeHelp) {
+    console.log('Usage: codex exec resume [--config key=value] [--json] THREAD PROMPT');
+  } else {
+    console.log('Usage: codex exec [--json] [--sandbox MODE] resume THREAD');
+  }
+  process.exit(0);
+}
+
+if (process.env.FAKE_CODEX_LAUNCH_LOG) {
+  appendFileSync(process.env.FAKE_CODEX_LAUNCH_LOG, `${JSON.stringify(args)}\n`);
+}
+
+if (args[0] === 'exec' && args[1] === 'resume') {
+  const configIndex = args.indexOf('-c');
+  const expected = `sandbox_mode=${process.env.FAKE_EXPECTED_SANDBOX ?? 'read-only'}`;
+  if (args.includes('--sandbox') || configIndex < 0 || args[configIndex + 1] !== expected) {
+    console.error('invalid resume sandbox contract');
+    process.exit(64);
+  }
+}
+
+const emit = (value) => console.log(JSON.stringify(value));
+const thread = process.env.FAKE_CODEX_THREAD ?? 'fake-thread-1';
+const started = () => emit({ type: 'thread.started', thread_id: thread });
+const verdict = () => emit({
+  type: 'item.completed',
+  item: { id: 'fake-item', type: 'agent_message', text: 'fake verdict' },
+});
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+switch (scenario) {
+  case 'silent':
+    await sleep(pause);
+    break;
+  case 'startup-byte-silence':
+    process.stderr.write('x');
+    await sleep(pause);
+    break;
+  case 'quiet-post-thread':
+    started();
+    await sleep(pause);
+    verdict();
+    break;
+  case 'malformed':
+    console.log('{definitely-not-json');
+    break;
+  case 'json-null':
+    emit(null);
+    break;
+  case 'json-array':
+    emit([]);
+    break;
+  case 'json-scalar':
+    emit('scalar');
+    break;
+  case 'item-null':
+    emit({ type: 'item.completed', item: null });
+    break;
+  case 'item-array':
+    emit({ type: 'item.completed', item: [] });
+    break;
+  case 'event-type-null':
+    emit({ type: null });
+    break;
+  case 'event-type-array':
+    emit({ type: [] });
+    break;
+  case 'item-type-null':
+    emit({ type: 'item.completed', item: { type: null } });
+    break;
+  case 'item-type-array':
+    emit({ type: 'item.completed', item: { type: [] } });
+    break;
+  case 'thread-non-string':
+    emit({ type: 'thread.started', thread_id: 42 });
+    break;
+  case 'verdict-non-string':
+    started();
+    emit({ type: 'item.completed', item: { type: 'agent_message', text: 42 } });
+    break;
+  case 'missing-thread':
+    verdict();
+    break;
+  case 'missing-verdict':
+    started();
+    emit({ type: 'turn.completed' });
+    break;
+  case 'exec-fail':
+    started();
+    console.error('fake execution failed token=super-secret');
+    process.exit(23);
+    break;
+  case 'split-secret':
+    started();
+    writeFileSync(2, `${'x'.repeat(65_530)}token=super-secret`);
+    process.exit(24);
+    break;
+  case 'signal':
+    process.kill(process.pid, 'SIGTERM');
+    break;
+  case 'group-hang': {
+    started();
+    const child = spawn(process.execPath, ['-e', 'setInterval(() => {}, 1000)']);
+    if (process.env.FAKE_CODEX_CHILD_PID) {
+      writeFileSync(process.env.FAKE_CODEX_CHILD_PID, String(child.pid));
+    }
+    await sleep(pause);
+    break;
+  }
+  case 'orphan-group': {
+    started();
+    const child = spawn(process.execPath, ['-e', 'setInterval(() => {}, 1000)'], { stdio: 'inherit' });
+    if (process.env.FAKE_CODEX_CHILD_PID) {
+      writeFileSync(process.env.FAKE_CODEX_CHILD_PID, String(child.pid));
+    }
+    child.unref();
+    break;
+  }
+  case 'pipe-burst':
+    process.stderr.write('x'.repeat(2 * 1024 * 1024));
+    started();
+    verdict();
+    break;
+  default:
+    started();
+    verdict();
+}