chore(plugin): delete comments from the runner, the Codex transcript resolver and the startup hook (#218) by ericlitman · Pull Request #221 · ericlitman/open-pstack

ericlitman · 2026-10-16T22:46:59Z

Part of #218. Applies the AGENTS.md no-comments rule (#219) to the plugin files this repository authored.

Summary

plugins/pstack/
├── hooks/session-start                         purpose paragraph deleted; Git Bash / Windows note stays
└── skills/poteto-mode/scripts/
    ├── resolve-codex-transcript{,.test}.ts     5 deleted; Codex user-record injection note stays
    │                                           + snapshot() reads only regular files (no empty catch)
    └── runner/                                 ~150 deleted across run.ts, types.ts, registry/, providers/

Scope: every changed file is absent from Cursor's pstack at the sync commit 99743e9. Upstream-derived files (watch-pr/, orch/, bootstrap.ts, check-plan.mjs, worktree-audit.sh, run-hook.cmd) are untouched.

What stays: 82 comment blocks. Each names a provider CLI's behaviour (agy, Amp, Claude Code, Codex, Cursor, Devin, dsh, Grok, OpenCode), a Git or Git for Windows behaviour, or the receipt's public writerSandbox field. Examples: Git older than 2.31 has no --path-format, Git localizes its messages, and dsh launcher flags must come before --json.

Two edits are not deletions:

The resolver test's snapshot() swallowed every read error to skip directories. It now reads only paths that stat as regular files, so the empty catch {} is gone.
RELEASED_PAIRS' comment said the list is append-only, and nothing enforced that. A registry.test.ts test now holds the count and SHA-256 of the 20 pairs released by 1.15.0, so the list's first 20 entries must keep that digest. Removing, reordering or rewriting a pair fails the test; appending passes. It stores a digest, not a copy, because the static pin invariant forbids pinned model names such as claude-opus-5 outside the registry.

Evidence

Comment-only check: a script parses each changed file before and after (TypeScript through the compiler printer, the hook with # comments dropped) and compares them with comments removed. On eb99918, all 28 files are comment-only. 9286600 adds the snapshot() change.
Resolver test after the snapshot() change: bun test resolve-codex-transcript.test.ts: 26 pass, 0 fail.
Generated catalog: bun runner/registry/render.ts --check exits 0, so model-catalog.md and the native agents are unchanged.

Live gate features. The run started 6 sessions from trusted main and passed (evidence). The code is unchanged, so each feature loads one changed file from the installed candidate:

codex:runner: runs the installed pstack-runner from a Codex parent. Its linked-worktree-writer case reaches discoverSharedGitDir in run.ts, whose comments changed.
claude:hook:startup and codex:hook:startup: hooks/session-start changed. The mandate must still reach a new session in both harnesses.
codex:skill-invocation:reflect (2 cases: locate-transcript, digest-fallback): Codex's Reflect runs the changed resolve-codex-transcript resolver. Claude's Reflect does not run it.

Merge Danger

Door: two-way

Blast Radius: none

The changed lines are comments, plus one test helper. A revert restores the comments.

Acceptance criteria

"The sweep covers only files that UPSTREAM.md, CHANGES.md and NOTICE.md identify as local adaptations or additions." Verified: every changed path is absent from pstack/ at 99743e9. NOTICE.md lists resolve-codex-transcript* as authored for this port, and the runner is port-authored.
"Each PR passes verify and the other required checks." See Gate results. CI verify, Unfret and live-gate report on this PR.
"MUST KILL reshapes that the sweep does not fix are listed in one follow-up issue." This PR fixes one flag (the snapshot() empty catch) and encodes one constraint (RELEASED_PAIRS is append-only). The other 12 reshapes, plus 4 constraints whose comments were deleted and that nothing enforces, go into the follow-up issue.

Gate results

On head 30d7a45:

Check	Exit
`bun run test` (502 tests)	0
`bun run typecheck`	0
`bun run static` (166 tests)	0
`claude plugin validate plugins/pstack`	0
`bun runner/registry/render.ts --check`	0

Earlier heads hit timing failures at load averages of 488 to 876 on the gate host. On 9286600 those were runLane > counts the Grok retry delay and the verifier's version-only manifest test, and each passed alone.

Review rounds

Head 9286600 (full panel): one blocking finding. The RELEASED_PAIRS append-only rule lost its comment and had no encoding, which breaks the AGENTS.md encode-then-delete rule. Class: verdict-changing. Fix: the digest test above. The test passes on the real list, fails with one pair deleted from models.ts, and passes with one pair appended.

Not verified

The kept vendor comments name CLI versions older than some installed CLIs (claude 2.1.288 vs 2.1.301, codex 0.159.0 vs 0.163.0, cursor-agent, devin, agy). The sweep did not re-measure them.

🤖 Generated with Claude Code

…resolver and the startup hook (#218) Applies the AGENTS.md no-comments rule to the plugin files this repository authored: poteto-mode's runner and its provider adapters, the Codex transcript resolver and its test, and the SessionStart hook. Comments that state a provider CLI, Git, Git for Windows or Codex fact stay, and so does the receipt's writerSandbox field doc. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

The snapshot helper swallowed every read error to skip directories. It now reads only paths that stat as regular files, so a real read error fails the test. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

mergify · 2026-10-16T22:47:35Z

Merge Protections

🟢 All 2 merge protections satisfied — ready to merge.

Show 2 satisfied protections

🟢 Queue ready pull requests

Automatically queue non-draft pull requests targeting main after verify, Unfret, and live-gate pass on the head and every review thread is resolved.

🟢 🚦 Auto-queue

When all merge protections are satisfied and these conditions match, this pull request will be queued automatically.

-files~=^\.github/
base = main

ericlitman · 2026-10-16T22:50:15Z

Live evidence: Open Pstack

Candidate SHA: 9286600aac9e083d01f2fc82b742c245dfbb4a32
Base SHA: 894570efec8f8a2b109d5a83a192f825e22023b7
Result: PASSED — named features verified
Self-test: not requested
Planned sessions: 6 (limit 12)
Publisher revision: 894570efec8f8a2b109d5a83a192f825e22023b7
Evidence-set SHA-256: c4c3b3593179a88a50b70c5c0a94facaf0abe87634c440a25dfe319463020c5f
Installation (claude): CLI 2.1.302 (Claude Code), plugin 1.15.0, candidate 9286600aac9e083d01f2fc82b742c245dfbb4a32, tree a7bc8750b3da863e6e26d07a45cb6baa8ba7256bd9ab8d21d523f453360f8566.
Installation (codex): CLI codex-cli 0.163.0, plugin 1.15.0, candidate 9286600aac9e083d01f2fc82b742c245dfbb4a32, tree a7bc8750b3da863e6e26d07a45cb6baa8ba7256bd9ab8d21d523f453360f8566.
Observation (claude / hook:startup): surface claude -p stream-json with the candidate plugin-dir; action recipe hook:startup: startup; result passed: startup:exit-0 startup:hook-context-injected; 2 assertions machine-checked; transcript SHA-256 798b94c5102962fa4173ecea7107b53f384b0a5fa2505eefe3dc782102f80f7c; artifact-set SHA-256 f0742b82d4de17cdfb0f1c51eb2e6e3e19ab9b7b741f57b1f407c9439a0bc2d6.
Observation (codex / runner): surface codex exec --json with the run-owned candidate installation; action recipe runner: route-1, linked-worktree-writer; result passed 10 assertions; ids retained privately; 10 assertions machine-checked; transcript SHA-256 5e09100bf46eb9b1be6b81bc0c9427e09bea52c2d7383c49acf60bd31122f3ce; artifact-set SHA-256 8d4bf8cb5ad9bd0ceb3838192592562b20d8d91ba4058b9d2bf399bb2cdf0f1a.
Observation (codex / hook:startup): surface codex exec --json with the run-owned candidate installation; action recipe hook:startup: startup; result passed: startup:exit-0 startup:hook-context-injected; 2 assertions machine-checked; transcript SHA-256 4ecee72688d91ddb1cd02c2a8504cd97f54ee6aa3105b10629eb0b225c6ddb0e; artifact-set SHA-256 f4f31ab397e71395a2f68e63f4efb68fcd9332ff854f66620e0e5d26733d3239.
Observation (codex / skill-invocation:reflect): surface codex exec --json with the run-owned candidate installation; action recipe skill-invocation:reflect: locate-transcript, digest-fallback; result passed 9 assertions; ids retained privately; 9 assertions machine-checked; transcript SHA-256 6adcf002a70620c8869e50b783d7120aa53d46264546ae87a8ea37692b5e4485; artifact-set SHA-256 75e82bd413397fdd1b77cb9567ccb5e49a3c2d038a601a23501550fc381faa12.
Policy: every new head requires a fresh run; this verifier does not change PR state, queue, or merge.

greptile-apps · 2026-10-16T22:51:03Z

[Low impact] The PR appears safe to merge; no actionable defect was found in the changed code.

Summary

Removes comments from the startup hook, Codex transcript resolver, and runner files. The only executable change makes the resolver test’s snapshot() read regular files without swallowing read errors.

The pstack runner and hooks keep working without most of their comments.
Resolver tests now snapshot regular files without swallowing read errors.

_{Reviews (1) · Last reviewed commit: "test(reflect): read only regular files i..." · Reviewed by Greptile}

unfret-eal · 2026-10-16T22:55:59Z

✅ No blocking findings

Walkthrough

This PR deletes about 150 explanatory comments from repository-authored plugin code: the pstack runner (`run.ts`, `types.ts`, `registry/`, `providers/` and their tests), the Codex transcript resolver and its test, and the `session-start` hook. Comments that describe external CLI, Git or Windows behavior are kept. Apart from the deletions, there are two small changes. The resolver test's `snapshot()` now reads only paths that stat as regular files instead of swallowing every read error. A new `registry.test.ts` case pins the count and SHA-256 of the first 20 `RELEASED_PAIRS` entries, so the append-only rule that the deleted comment described is now enforced by a test. The author reports that a script showed the swept files differ only in comments, and that the test, typecheck, static and catalog-render checks passed on the final head.

Area	What changes
Comment removal	Deletes descriptive and doc comments across the runner, registry, provider adapters, their tests, the Codex transcript resolver and the session-start hook. Code is otherwise unchanged; one `catch` in `run.ts` is now empty after its comment was removed.
Resolver test helper	`snapshot()` checks `statSync(path).isFile()` before reading, replacing a `try/catch` that ignored directory read errors.
Released-pairs guard	Adds a test that hashes the first 20 released model pairs and compares the result to a fixed digest, so removing, reordering or editing any of them fails while appending still passes.

Since the last review

Fixed: RELEASED_PAIRS append-only rule deleted without encoding. Why: The carried repair is satisfied at the current head. The newly added count-and-digest assertion pins every one of the 20 existing released pairs, including claude:claude-fable-5, claude:claude-opus-5 and grok:grok-4.6. Deleting any of these entries now changes the hashed prefix and fails the test; retaining an entry while breaking its family resolution fails the adjacent resolution test. Thus the earlier claim that only surviving entries are checked is no longer true, and the previously confirmed encode-before-delete failure is repaired. This existing-history scenario is separate from finding-0000 and finding-0001's hypothetical future unpinned additions.

Details

Lane / stage	Model	Effort	Outcome	Duration
broad-gpt-5.6-sol-xhigh / review	openai/gpt-5.6-sol → gpt-5.6-sol · primary	xhigh	succeeded	2 min 25 s
broad-opus-5.5-max / review	anthropic/claude-opus-5-5 → claude-opus-5-5 · primary	max	succeeded	12 min 30 s
focal-gpt-5.6-sol-xhigh copy / review	openai/gpt-6.1-sol → gpt-6.1-sol · primary	xhigh	succeeded	6 min 25 s
focal-gpt-5.6-sol-xhigh copy 2 / review	openai/gpt-6.1-sol → gpt-6.1-sol · primary	xhigh	succeeded	6 min 37 s
judge / judge	openai/gpt-6-astra → gpt-6-astra · primary	high	succeeded	47 s

Reviewed the whole pull request.
4 reviewers finished.
Commit 30d7a45.
Check run.
Run: GET /unfret/run/panel:30d7a45f00e4dc933aa47cb3cc456ea9b2fa2442:bts31OtgIcp:DyqgVPR4oI0.

_{@unfret review · @unfret status · @unfret help}

unfret-eal

🛑 1 blocking finding
🔵 Low · RELEASED_PAIRS append-only rule deleted without encoding
Check

The sweep deleted RELEASED_PAIRS' "append-only" comment. The rule is now a test: the first 20 entries, the pairs released by 1.15.0, must keep their SHA-256, so removing, reordering or rewriting one fails and appending passes. A digest instead of a copy keeps pinned model names out of the test, as the static pin invariant requires. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

ericlitman · 2026-10-16T23:04:33Z

Live evidence: Open Pstack

Candidate SHA: 30d7a45f00e4dc933aa47cb3cc456ea9b2fa2442
Base SHA: 894570efec8f8a2b109d5a83a192f825e22023b7
Result: PASSED — named features verified
Self-test: not requested
Planned sessions: 6 (limit 12)
Publisher revision: 894570efec8f8a2b109d5a83a192f825e22023b7
Evidence-set SHA-256: 6a53051546ccb19cf454522d7b302233e45c19182610d9b5503c031ed04cd9ca
Installation (claude): CLI 2.1.302 (Claude Code), plugin 1.15.0, candidate 30d7a45f00e4dc933aa47cb3cc456ea9b2fa2442, tree 9d7e979fd31237a09c19bf93b23127df18d3cd9336f2537e8a6a5ab127f23b39.
Installation (codex): CLI codex-cli 0.163.0, plugin 1.15.0, candidate 30d7a45f00e4dc933aa47cb3cc456ea9b2fa2442, tree 9d7e979fd31237a09c19bf93b23127df18d3cd9336f2537e8a6a5ab127f23b39.
Observation (claude / hook:startup): surface claude -p stream-json with the candidate plugin-dir; action recipe hook:startup: startup; result passed: startup:exit-0 startup:hook-context-injected; 2 assertions machine-checked; transcript SHA-256 86f31e453986371958f188e13a93d7828b2323104c2aab109493ffc22ba071a6; artifact-set SHA-256 f0742b82d4de17cdfb0f1c51eb2e6e3e19ab9b7b741f57b1f407c9439a0bc2d6.
Observation (codex / runner): surface codex exec --json with the run-owned candidate installation; action recipe runner: route-1, linked-worktree-writer; result passed 10 assertions; ids retained privately; 10 assertions machine-checked; transcript SHA-256 0cf9a83d5f7e22c5bcc797568d47460c4697e1c25606f3569729c9ace27a85c8; artifact-set SHA-256 56f70ac413c9461a03bf6fa3633b8ac667d7a200ba021c6efc2873d8f384c854.
Observation (codex / hook:startup): surface codex exec --json with the run-owned candidate installation; action recipe hook:startup: startup; result passed: startup:exit-0 startup:hook-context-injected; 2 assertions machine-checked; transcript SHA-256 0d1566d6707a3998760eef7d968c71126cf6e0929981cae97b9aeb467e606869; artifact-set SHA-256 8cc43ea2e2d5dcacaeae256cff57c6e7bdc16db84e684f34f43c9f82351ad963.
Observation (codex / skill-invocation:reflect): surface codex exec --json with the run-owned candidate installation; action recipe skill-invocation:reflect: locate-transcript, digest-fallback; result passed 9 assertions; ids retained privately; 9 assertions machine-checked; transcript SHA-256 5fe88e9724c731ff87479dd73fa813d3c7468a3d69e680474bc3fbccc8d61921; artifact-set SHA-256 55076b21235138c07bdf507cbab9993557b705cd51272511d4e12f2c0b059c06.
Policy: every new head requires a fresh run; this verifier does not change PR state, queue, or merge.

unfret-eal

✅ No blocking findings
Check

mergify · 2026-10-16T23:17:37Z

ericlitman and others added 2 commits October 16, 2026 18:41

test(reflect): read only regular files in the Codex home snapshot (#218)

9286600

The snapshot helper swallowed every read error to skip directories. It now reads only paths that stat as regular files, so a real read error fails the test. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

unfret-eal Bot reviewed Oct 16, 2026

View reviewed changes

Comment thread plugins/pstack/skills/poteto-mode/scripts/runner/registry/models.ts

unfret-eal Bot reviewed Oct 16, 2026

View reviewed changes

mergify Bot merged commit b53c4de into main Oct 16, 2026
6 checks passed

This was referenced Oct 16, 2026

Reshape the owned code that the comment sweep flagged MUST KILL #222

Open

Adopt the no-comments rule for local content and sweep its existing comments #218

Closed

Navigation Menu

Repository navigation

chore(plugin): delete comments from the runner, the Codex transcript resolver and the startup hook (#218) - #221

chore(plugin): delete comments from the runner, the Codex transcript resolver and the startup hook (#218)#221
mergify[bot] merged 3 commits into
mainfrom
chore/218-sweep-plugin-comments

ericlitman commented Oct 16, 2026 •

edited

Loading

Uh oh!

mergify Bot commented Oct 16, 2026 •

edited

Loading

🟢 Queue ready pull requests

🟢 🚦 Auto-queue

Uh oh!

ericlitman commented Oct 16, 2026

Uh oh!

greptile-apps Bot commented Oct 16, 2026 •

edited

Loading

Uh oh!

unfret-eal Bot commented Oct 16, 2026 •

edited

Loading

Uh oh!

unfret-eal Bot left a comment

Uh oh!

Uh oh!

ericlitman commented Oct 16, 2026

Uh oh!

unfret-eal Bot left a comment

Uh oh!

mergify Bot commented Oct 16, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

ericlitman commented Oct 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Evidence

Merge Danger

Acceptance criteria

Gate results

Review rounds

Not verified

Uh oh!

mergify Bot commented Oct 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merge Protections

🟢 Queue ready pull requests

🟢 🚦 Auto-queue

Uh oh!

ericlitman commented Oct 16, 2026

Live evidence: Open Pstack

Uh oh!

greptile-apps Bot commented Oct 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Uh oh!

unfret-eal Bot commented Oct 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ No blocking findings

Uh oh!

unfret-eal Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ericlitman commented Oct 16, 2026

Live evidence: Open Pstack

Uh oh!

unfret-eal Bot left a comment

Choose a reason for hiding this comment

Uh oh!

mergify Bot commented Oct 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merge Queue Status

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

ericlitman commented Oct 16, 2026 •

edited

Loading

mergify Bot commented Oct 16, 2026 •

edited

Loading

greptile-apps Bot commented Oct 16, 2026 •

edited

Loading

unfret-eal Bot commented Oct 16, 2026 •

edited

Loading

mergify Bot commented Oct 16, 2026 •

edited

Loading