## Thinking Path
> - Paperclip runs AI agents through adapter execution services.
> - The adapter runtime records spans for each stage of agent startup.
> - The managed runtime packs workspace tarballs before it uploads them.
> - These pack operations had no host span, so `stage.sync` omitted pack
time.
> - This pull request adds one `pack` span around both tarball builds.
> - The span nests under the active `stage.sync` step and improves trace
detail.
## Linked Issues or Issue Description
**What existing behavior does this improve?**
The managed runtime workspace sync builds a git-history tarball and a
workspace-overlay tarball before upload.
**Subsystem affected**
The change affects `packages/adapter-utils`, which provides adapter
execution and managed runtime support.
**Current behavior**
The host builds both tarballs without an OpenTelemetry span. The
`stage.sync` trace therefore omits the host pack duration.
**Proposed behavior**
The host wraps both tarball builds in one `pack` span. The executor
parents this span under the active startup step.
**Reason and benefit**
The trace shows the time that the host spends packing workspace data.
Operators can use the existing runtime span tree to find sync delays.
**Breaking changes**
None. The default span runner remains a no-op runner, and the existing
control flow remains unchanged.
## What Changed
- Add an optional `runtimeSpan` runner to the managed runtime
preparation path.
- Create one host `pack` span around the two workspace tarball builds.
- Parent the `pack` span under the active startup step.
- Add unit coverage for span emission and span nesting.
## Verification
- Run `tsc --noEmit` for `@paperclipai/adapter-utils`.
- Run the `@paperclipai/adapter-utils` Vitest suite.
- Confirm the suite reports 448 passed tests and 4 skipped tests.
- Confirm the trace test records `pack` under `stage.sync`.
## Risks
The change adds optional tracing only. The default no-op runner
preserves behavior when tracing is not configured.
## Model Used
OpenAI Codex, GPT-5, tool use and code execution. The model reviewed the
handoff and opened this pull request. The implementation author supplied
the commit.
## 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
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
Co-authored-by: Paperclip <noreply@paperclip.ing>
d5208d30c1