## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - Codex thread state arrives as provider-specific goals, lineage,
notifications, and workspace paths
> - That data must be normalized before the full driver can retain or
project it
> - Notifications also need run and thread binding so unrelated provider
traffic is ignored
> - This pull request adds pure normalization helpers before the full
driver
> - A later pull request will use these helpers for the Codex session
lifecycle
> - The benefit is a small, independently tested trust boundary for
thread state
## Linked Issues or Issue Description
**Subsystem affected**
`packages/paperclip-runner` Codex thread-state normalization.
**Problem or motivation**
Provider thread data can contain unsupported goal shapes, unrelated
notifications, unsafe workspace paths, or unbounded response values.
Passing it through directly would weaken run isolation and durable-data
bounds.
**Proposed solution**
Normalize goals and lineage into stable runner shapes, accept
notifications only when their run and thread identities match, constrain
workspace references to the assigned root, and retain only bounded safe
provider responses.
**Alternatives considered**
Keeping these rules embedded in the full driver would make the trust
boundary harder to review and test independently.
**Roadmap alignment**
This supports the Codex-first experimental runner. It does not enable
the runner adapter.
## What Changed
- Added normalized Codex thread goals and lineage.
- Added run- and thread-bound notification filtering.
- Added safe workspace-relative path and stat projection.
- Added bounded provider-response retention.
- Added focused normalization and isolation tests.
## Verification
- `pnpm --filter @paperclipai/paperclip-runner test:typescript`
- `pnpm -r typecheck`
- `pnpm build`
- The focused thread-normalization test has 3 passing cases.
## Risks
The main risk is retaining data from the wrong provider thread or
accepting an unsafe workspace reference. Tests cover identity binding,
path normalization, response bounds, goal parsing, and lineage
projection.
## Model Used
OpenAI Codex with GPT-5.6 and repository tool use.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
Dotta