[parked] docs(design): plan removal of cold-turn startup costs (pi-acp probes, eager mount)

[mmabrouk]

Symptom

On a cold turn (the first turn of a conversation), the agent takes about two seconds
longer to begin answering than the model itself needs. Profiling the live local runner on
2026-07-11 attributed the delay to two unrelated causes, and this PR is the plan to remove
both. It is a design-and-research PR: no code changes, only a planning workspace.

Measured causes

• Pi adapter startup probes, about 1.6s (Fix A). At every cold session start the pi-acp
  adapter runs pi --version twice and npm view @earendil-works/pi-coding-agent version
  once, serialized before the first model request. Each pi --version is about 440ms; the
  npm view is about 230-280ms over the network. The runner already deletes the banner these
  probes produce (services/runner/src/tracing/otel.ts), so it pays 1.6s to produce text it
  throws away. The same probes run inside Daytona sandboxes, where npm view reaches npm from
  a European sandbox.
• Eager durable mount, about 0.55-0.6s (Fix B). acquireEnvironment
  (services/runner/src/engines/sandbox_agent.ts) mounts the durable working directory with
  geesefs before opening the session, even on a chat-only turn that never touches a file.

What the plan contains

• research.md: code-verified findings. The most important one: the pi-acp copy that runs
  the probes is very likely not the runner's patchable pi-acp@0.0.29 dependency. The
  @sandbox-agent CLI installs its own copy (0.0.31, floating range) from the ACP registry
  outside the repo, and does the same inside Daytona. So the pnpm patch mechanism may not reach
  the running copy, and definitely does not reach the sandbox copy.
• plan.md: staged Fix A (turn on quietStartup with no patch to remove one probe; remove the
  unconditional update-notice probe; retire the otel.ts banner-stripping; reach the Daytona
  copy; add a timing regression guard), with Fix B deferred to a measured follow-up.
• open-questions.md: the runtime facts that gate the work, chiefly which adapter copy runs.

Verdict on Fix B

Fix B is genuinely complicated and the plan recommends shipping Fix A alone. The eager mount is
required, not incidental: workspace files (AGENTS.md, skills, harness files) are written into
the mount so they persist, and a FUSE mount placed over a directory hides what it already held,
so a late mount would shadow those files and any the harness wrote. The safer "overlap the mount
with the harness cold start" variant is bounded by a timing window not yet measured. Details in
research.md.

https://claude.ai/code/session_018MaXPNpvzN22kngHno3VMj

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agenta-documentation	Ready	Preview, Comment	Jul 11, 2026 1:26pm

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 9ccb22b4-cb52-4111-93f9-2a58994ddf93

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/cold-turn-startup-plan

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[mmabrouk]

Folded in the upstream pi-acp research Mahmoud asked for (commit b034041). What changed:

No newer version fixes it. npm latest is 0.0.31 (2026-06-17), the same version the sandbox-agent CLI installs, and upstream HEAD (github.com/svkozak/pi-acp, active, 498 stars) still runs both probes unconditionally. The README explicitly confirms quietStartup does not cover the update check. So the "pin to a fixed version" shortcut does not exist today; the patch strategy stands.

But the version is effectively pinned, and there are clean delivery levers. The ACP registry entry pins pi-acp@0.0.31 exactly (the ^0.0.31 in the installed package.json is npm's artifact; the lockfile pins it). The CLI honors a pre-seeded agent_processes/pi/ directory ("already installed" short-circuit), which makes snapshot pre-seeding the clean fix for the in-sandbox copy, and SANDBOX_AGENT_ACP_REGISTRY_URL / SANDBOX_AGENT_REQUIRE_PREINSTALL give a registry-override and a fail-loud lever. plan.md Stage 2/4 rewritten around this; open-questions.md question 4 is now mostly answered.

Upstream is worth engaging. Open issue svkozak/pi-acp#70 already complains about the same update-check notice (on protocol grounds, not latency), and upstream has precedent for a settings-gated startup switch. Added Stage 2b: file the latency issue proposing checkForUpdates: false, with a ready-to-file draft in upstream-issue-draft.md. An upstream release is the retirement path for our patch, not the delivery path.

Numbers updated. Daytona in-sandbox probes measured today at ~2.0s (two pi --version at ~750ms + npm view ~305ms), worse than the local 1.6s, so Stage 4 is the largest single saving. Also noted the interaction with the separate AGENTA_AGENT_SANDBOX_PI_INSTALLED=false change: with the install skipped, PI_ACP_PI_COMMAND is no longer set and the adapter resolves the baked /usr/local/bin/pi, so Stage 0's which-copy-runs check must run with that setting in its final state.

https://claude.ai/code/session_018MaXPNpvzN22kngHno3VMj