docs: Pi reasoning and profile provenance (3/5) (#14923)

## Thinking Path

> - Paperclip manages AI agents and their work.
> - The experimental Runner owns provider processes and durable
sessions.
> - Pi needs working task execution and human controls.
> - The five-PR stack must preserve changes already on master.
> - The runtime implementation has merged in #14921; this layer carries
the next documentation changes.
> - This PR belongs to native GitHub stack #15602, ending at #14956.

## Linked Issues or Issue Description

Refs #14436, #14631, #14743 and #14956.

Ship Pi 1.0 through the experimental Paperclip Runner. The five PRs are
#14921, #14922, #14923, #14924 and #14956. The user authorized the
complete merge after checks pass. Existing `pi_local` execution is
unchanged. Accounting and wider provider/platform qualification remain
deferred.

## What Changed

- Document explicit Pi reasoning selection and native acknowledgement.
- Preserve historical Pi and shared Copilot profile provenance and
qualification outcomes.

## Verification

- Full local `pnpm -r typecheck` passes, including Runner Rust, server
and UI. Focused integration checks pass: 194 Runner
admission/environment tests, 63 profile/credential tests with one
expected skip, 152 Dot/UI configuration tests, and Pi transcript/notice
tests.
- Full local `pnpm build` passes on the final source.
- Fresh final-source checks pass: all 698 Rust workspace tests (32
binaries), 156 credential/profile/controller tests with one expected
skip, Runner TypeScript typecheck, and 20 package/setup/sandbox tests.
- The profile-21 Pi materializer passes on the native host with the
official pinned Node 24.21.0 and its npm. It verifies all 150 locked
packages, the patched dependency and the exact closure. Setup/package
bundle tests and UI token gates pass.
- The old hashes were reproduced for all three supported targets before
calculating the patched graph. New closure hashes are darwin-arm64
`282022db10150c6632b3444df421342e7d534bdf5d5fb1097a2e79d0625a2bcf`,
darwin-x64
`64e251e19009f755c0b04f73ce2138246faab71a961b0f13d75ebfcc34bef12e`, and
linux-x64
`713b1fdff42fb56a1518bdc084f181d70bee8ebadc3e4b1d76321ed9108c8410`.
Independent native platform execution is separate from graph identity
reproduction.
- Historical cloud qualification remains unchanged: all seven core cases
pass on shipping source `10dc43c9ec65d88c2f782d62afb296d09494f215`,
harness `1a4408a48cfb5a1f094a311141c257c92cd7a893`, image
`sha256:5b3a775b383591bda1b0c1889e509acc70ce7f37c53f09733c81d59037f02280`,
and accepted Sonnet 4.6/low fixture. All 215 canonical files and all
seven cleanup checks pass independent verification. These are profile-19
results and are not relabeled as fresh profile-22 runs.
- Current Pi digest:
`sha256:e92078bee3c23bec4100aa589013a44613d054cd686826534025d8019e9f39a9`.
[The readiness
plan](https://github.com/paperclipai/paperclip/blob/codex/pi-production-readiness/doc/plans/2026-10-02-pi-production-readiness.md)
preserves campaign and failed-attempt provenance.
- Merge only after every PR's current-head CI and fresh review pass.
Linux CI covers the full suites, build and browser tests. The local
embedded Postgres API-authority suite cannot start on this macOS/Node 26
host, so Linux CI must confirm that suite.

### Fresh profile-22 core qualification — 2026-10-08

All seven accepted core cases pass canonically on Pi profile 22, with
`openrouter/anthropic/claude-sonnet-4.6` and native-confirmed low
thinking. This model is a fixture; production accepts the caller's
explicit Pi provider/model.

Runtime/install source: `3241a992f2a7703e59e97ed0fd3e5d6405de4401`.
Frozen accepted harness: `1a4408a48cfb5a1f094a311141c257c92cd7a893`.
Immutable cloud image:
`ghcr.io/paperclipai/paperclip-daytona-runner@sha256:506f22db7edd78f37c0c40bec1cc084af1850455026dbf467194bfbb8fcef141`.
Pi digest:
`sha256:e92078bee3c23bec4100aa589013a44613d054cd686826534025d8019e9f39a9`.

[Hosted Linux image and clean-install
verification](https://github.com/paperclipai/paperclip/actions/runs/37868328023)
passes, including all 20 source-bound archives, normal CLI/Pi setup,
companion import and the production pack reader. This exact installation
source includes the latest master integration and the corrected Pi warm
instruction-root fence. Full local typecheck/build and current-head
hosted CI verify the final stack. All 13 focused real-root regressions
pass. The full local executor suite passed 662 tests; 15 database tests
could not start the Mac embedded PostgreSQL service. Hosted Linux CI
passes the full required verification and E2E checks. These fresh
results keep their own source identity; profile-19 results remain
historical.

| Core path | Canonical campaign | Retained archive SHA-256 |
| --- | --- | --- |
| File edit, validation, download and Done |
`pi-core22-replyfix-0-1791511228` | 23 files;
`a473e8603a3dd4737863291f8d3d1e392391f0b16d433c3e0e0e9d8baf7a97b0` |
| Pending question and controller restart |
`pi-core22-replyfix-1-1791511376` | 33 files;
`6b829c4eb74e1f32a89c692a4ae7130dbfc1c6d3cf13915effe2103d9e242c8e` |
| Three-turn session/process/workspace continuity |
`pi-core22-replyfix-2-1791511587` | 23 files;
`7a87021f8f9a3fdd3c58bb4467f8d82c635e3ea4795d6e75f144d9aa14818df8` |
| Four typed questions and browser reconnects |
`pi-core22-replyfix-3-1791511881` | 42 files;
`9e31755252be1f4f9cb0626c984c142d4d1ae5f5bee3a7af08444db8d12c280a` |
| Plan approval and completion | `pi-core22-replyfix-4-1791512031` | 22
files;
`a0383ce1aab38e7b5a25ce0e9dd3bebea5c037ebd96ae6b29dae19015da2ae2c` |
| Same-turn steering and permission denial |
`pi-core22-replyfix-5-1791512261` | 39 files;
`c929b8c7070f0b66aedc17e65ca46e6beab1e363926ac9f7e2a75fb250f05949` |
| Stop during pending permission | `pi-core22-replyfix-6-1791512390` |
33 files;
`7f0a58ae0f4d5bfc76149435f4e322537089c5bd16e7ffe9b5ad71f10a621a07` |

All 215 canonical files (28714587 bytes) are independently
hash-verified. All seven cleanup grades pass, with no owned runtime
process or temporary root after each case. Automatic retries are zero.
The owned cloud host stopped normally after retention. The prior
profile-22 warm attempt remains failed and separately retained: archive
SHA-256
`1e54eba5ec72b50cee1534b23d1d1d4f21a090006b8a64501ba70db972abfde5`. Its
original canonical classification is preserved. Diagnosis reproduced a
product bug comparing an agent-files root against an unset
checkpoint-only field. The fix stores the admitted physical root
separately from the adopted per-run collection capability. The real-root
regression fails before the fix and passes afterward, including
rejection of a changed physical root. Fixture, grader, model and all
seven accepted case IDs are unchanged; this fresh campaign tests
final-reply publication after file registration first. The intermediate
restart attempt also remains failed and retained: archive SHA-256
`5dcaefdf1d17cf4cd54fd4cf810f45e736667392339b8ce7caf08bb4e225277f`. Its
original canonical classification is preserved. Pi resumed, wrote the
verified answer and completed its task; exact runner suspension was
proven, but idle stop consumed about 5.2s and left under 3s for the
drain acknowledgement. The Pi-only default shutdown grace is now 15s,
preserving a full 5s drain round trip and a finite suspension reserve.
Explicit caller deadlines, other provider defaults, literal drain
receipts and exact suspension identity checks remain unchanged. The
timing regression fails before this correction and passes afterward; all
18 focused settlement tests and Runner typecheck pass. The final-source
file attempt is also preserved as failed (`candidate_failure`), archive
SHA-256
`db6767b6773ea618997927ac77bdb005a5ac81492c7b9c0ffbc900449f829bc9`.
Native edit, validation, exact downloadable artifact and Done/succeeded
all passed, and the exact final reply was durably recorded. A workspace
recovery owner completed before the live heartbeat reached presentation,
leaving that reply absent from task chat. Recovery now materializes only
a completed final reply from the accepted turn of an ordinary internal
Done task, preserving issue/run/contract binding, suppression,
external-chat authorization and same-run deduplication. The database
regression covers the generated file-preparation receipt, suppression,
unapproved external continuation and replay. Server typecheck and all 49
response-selection tests pass; hosted Linux verifies the database
regression because embedded PostgreSQL cannot start on this Mac.

The delayed-final-answer database regression passes on [the final
root-source Linux server
shard](https://github.com/paperclipai/paperclip/actions/runs/37868262553/job/113628594152),
alongside 1,108 passing tests. The first root Runner shard had one
unchanged durable-resume test exceed its 5-second timeout; the identical
top-source shard and the isolated exact test passed. One rerun of that
failed job and its required aggregate passed without source or test
changes. The original failed job log and the single-rerun receipt remain
retained.

### October 9 merge verification

Current merge head: `1b4d7acf38fb8a7ded0d5efe76ef1f2d744e6ea0`. All
current-head checks pass, including `ci / verify` and `ci / e2e`;
exact-head Greptile review is 5/5 with no unresolved threads. Current
master conflicts are resolved. The user authorized the maintainer
override of the code-owner review gate after these checks. The seven
retained live core cases remain bound to source
`3241a992f2a7703e59e97ed0fd3e5d6405de4401` and its recorded cloud image.

## Risks

- The security correction changes the dependency closure and profile
identity. Old sessions must reopen on the new profile. Exact identities
and credential bindings fail closed.
- The runner remains experimental and requires explicit selection.
Legacy Pi Local is unchanged. Caller model IDs pass through; the E2E
model is a fixture.
- Accounting and the broad platform/provider matrix remain deferred.
This merge does not publish a release or deploy a service.

## Model Used

OpenAI GPT-6 through Codex assisted with reasoning, repository
inspection, editing and tool use. The exact serving ID and context
window are not exposed in this session. Final live qualification uses Pi
1.0.0 with `openrouter/anthropic/claude-sonnet-4.6` and native-confirmed
low thinking.

## 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
#` 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
This commit is contained in:
Dotta authored and GitHub committed 2026-10-09 10:34:07 -05:00
1 parent 2eb5187e43
commit e265f94443
3 files changed
+135 -52

No files matched your search

@@ -6,7 +6,17 @@ It binds master's shared protocol-validation sources without changing the
executable or supplying new paid qualification. Historical checkpoints below
retain their original identities and outcomes.
Historical source candidate (2026-10-01): **Copilot profile v12 is unqualified**.
Historical source candidate (2026-10-02): **Copilot profile v13 is unqualified**.
Pi's explicit reasoning-mode support changed four shared transport and schema
source files included in Copilot's execution identity. Version 13 records those
source hashes with digest
`sha256:3ff08fbe76fe4549c9eb01e8794428d8909c65c151d775220f2ec111d9e6f7c1`.
The Copilot executable closure, model and provider behavior are unchanged. The
historical v12 declaration is preserved; v12 warm sessions are rejected by the
current candidate. This identity update supplies no new paid qualification.
Fresh runtime packages and local/Daytona qualification remain required.
Historical source candidate (2026-10-01): **Copilot profile v12 was unqualified**.
Receipt v2 preserves the original `inputSha256` and separately captures
`normalizedInputSha256` from the same invocation's validated outgoing body.
For the native sidecar, only a successful, correlated `tool.resolve` commits
+52 -1
View File
@@ -22,7 +22,58 @@ for the exact source/image evidence and merge status.
All dated checkpoints below describe historical qualification attempts. Their
failures and profile numbers are retained; they are not current release gates.
## Historical Pi 1.0 candidate (2026-10-02, profile v12)
## Historical Pi 1.0 candidate (2026-10-02, profile v13)
Pi remains pinned to **`@earendil-works/pi-coding-agent@1.0.0`**, with
`pi-acp@0.0.33`, ACPX `0.13.1`, and Node `24.21.0`. Profile 13 adds explicit
reasoning-mode selection and rejects previous profile identities. It is a new
qualification candidate; profile-12 results below remain historical evidence.
Pi's new field also changes four shared files covered by Copilot's source
identity. Copilot therefore advances to a still-unqualified profile v13 without
changing its executable or model. Pi's profile-13 identity and native closure
remain unchanged. Final artifacts must bind the corrected source; the initial
ARM startup and 61 contract passes alone do not establish production readiness.
The normal Pi configuration records `piThinkingLevel` as `off`, `low`, `high`,
or `max`. New configurations and qualification cases explicitly select `low`.
The runner binds that setting to the session identity and requires native
confirmation of the effective level before sending the prompt, including after
session restoration. An unsupported level, absent acknowledgement, or effective
level different from the requested value must fail admission. Changing the
level requires a new compatible session; a warm session cannot silently retain
its previous setting.
The wrapper obtains available levels from Pi's native
`get_available_thinking_levels` RPC, exposes them through ACP session modes and
the `thought_level` configuration option, and confirms changes with native
`get_state`. This avoids advertising the static `minimal`, `medium`, or `xhigh`
aliases when the selected model does not support them. For the pinned DeepSeek
model, Pi 1.0 supports `off`, `low`, `high`, and `max`. Pi's implicit `medium`
default resolves to `high`; Pi 0.84.2 also resolved that default to `high`, so
this is a configuration gap rather than evidence of a new Pi 1.0 default.
The [provider-free wire proof](../../packages/paperclip-runner/test-fixtures/pi-acp/thinking-modes.v13.darwin-arm64.json)
records actual Pi 1.0 request bodies changing from `high` to `low` through ACP,
truthful `max` restoration, blocked non-loopback connections, and owned-process
retirement. Synthetic responses establish propagation, not paid qualification.
The paid profile-12 hello passed in the actual installed application. Its first
question continuation failed at the unchanged 120-second native deadline after
1,019 reasoning deltas and no emitted tool call or question. The required tool
was present with its exact schema. This establishes model activity without the
required interaction; it does not prove the reasoning setting caused the timeout.
The test remains failed. Profile-13 deterministic, local paid, Runner, native
control, and Daytona results must be established independently.
| Capability | Native / ACP surface | Paperclip surface | Remaining boundary |
| --- | --- | --- | --- |
| Supported thinking levels | `get_available_thinking_levels`; ACP available session modes and `thought_level` choices | Pi reasoning-level configuration | Model selection is explicit and unrestricted; historical qualification used the recorded model and level. |
| Set and verify thinking level | Native `set_thinking_level`, then `get_state`; ACP `session/set_mode` / config option | Saved agent setting, typed runner input, effective-mode admission | Live setting changes during an active turn are not exposed; a new compatible session is required. |
| Recover selected level | Native restored state plus explicit effective-level verification | Mode-bound durable session identity | Old profiles and missing or mismatched mode identity cannot reuse a warm session. |
| Provider notice severity and pricing provenance | `paperclip/pi_notice` and canonical `provider.notice.recorded` | Retained run event and usage metadata | The activity row currently renders a generic provider-update label and warning icon even for informational pricing estimates. P2: render the safe summary and severity; do not imply an estimated price is a bill. |
## Historical Pi 1.0 profile-v12 checkpoint (2026-10-02)
The candidate now pins **`@earendil-works/pi-coding-agent@1.0.0`** with
`pi-acp@0.0.33`, ACPX `0.13.1`, and portable Node `24.21.0`. Pi v11 and older
@@ -24,64 +24,86 @@ failures and profile numbers are retained; they are not current release gates.
## Historical Pi 1.0 qualification checkpoint — October 2, 2026
Pi now uses `@earendil-works/pi-coding-agent@1.0.0`, `pi-acp@0.0.33`,
ACPX `0.13.1`, and profile **12**. Its exact model remains
`openrouter/deepseek/deepseek-v4-flash-0731`. Cursor v10 and Copilot v12
remain gated while Pi qualification is completed. The held Pi admission branch
is preparation for testing normal installation; it is not production qualification.
Pi uses `@earendil-works/pi-coding-agent@1.0.0`, `pi-acp@0.0.33`, and ACPX
`0.13.1`. Profile **13** adds explicit, native-acknowledged reasoning selection
for the exact model `openrouter/deepseek/deepseek-v4-flash-0731`. New Pi
configuration and qualification cases select `low`. This candidate is not yet
production qualified. Cursor v10 and Copilot v13 remain gated.
The first paid Pi 1.0 local hello on profile 11 failed: Pi's serialized RPC
message updates no longer carry the old SDK-shaped partial message. That failure
is retained, with $0.000142518 observed on the dedicated OpenRouter key and
complete owned-process cleanup. Profile 12 repairs the actual RPC boundary;
its local-only tests exercise the real Pi CLI, wrapper and owned extension.
They do not replace authenticated product tests.
Copilot's declaration hashes the shared sidecar, sidecar protocol, direct driver,
and generated schema bundle. Pi's reasoning field changed those four files, so
Copilot's pending declaration advances to v13 with digest
`sha256:3ff08fbe76fe4549c9eb01e8794428d8909c65c151d775220f2ec111d9e6f7c1`.
Its executable, distribution closure, model, permissions, and qualification
status are unchanged. The v12 declaration remains historical, and v12 warm
sessions are rejected. This source-identity repair supplies no Copilot paid proof.
At runtime source `b9e5d6ecdb05ab7244c90976e07c950f8d09b15b`, the fresh
macOS ARM64 daemon and verified pack pass the original no-key startup test
(6.741 seconds to settlement) and all 48 native/ACP contract tests without skips.
The original evidence collector rejected Node 24's summary format after the
runtime checks had passed. Its failure is preserved; independently reviewed
offline finalization verifies those same logs and full asset inventories without
rerunning the tests. The fresh native Intel build also passed all 48 contract
tests, but its canonical startup failed at the unchanged 30-second deadline
(35.032 seconds to settlement). A later instrumented run passed at 22.959 seconds;
it used a read-verified, warmed filesystem state and does not erase the original
failure. A four-run I/O-pool comparison was inconclusive, so no production
thread-pool change was adopted. Intel startup and the final installed-package
local/Daytona tests remain separate gates.
The first profile-13 source (`f5c5fde38`) built a fresh ARM daemon and Pi pack,
then passed original startup and all 61 native/ACP contract tests without model
calls. Its full Runner suite found three missing-mode test fixtures and the
stale Copilot declaration. Those failures are retained. The corrected final
source still requires fresh platform builds, complete checks, and paid tests.
Testing the actual public package installation exposed a packaging defect:
ambient npm 10 pruned 84 files from the pinned Pi dependency closure. Setup now
uses npm 11.19.0 bundled in the independently verified Node archive. The repaired
provisioner reproduces the original profile-12 closure with ambient npm disabled;
fresh public-package installation proof remains required.
Profile 12 passed one paid local hello through the actual installed public
CLI/server and normal runtime setup. The next question-continuation case failed
at the unchanged 120-second native deadline: Pi emitted 1,019 reasoning deltas,
but no tool call or question. The tool and schema were present. One native turn
was submitted; the two visible start rows were canonical and mirrored activity,
not evidence of two provider requests. Both attempts completed owned-process,
IPC, temporary-root, installed-inventory, and post-run accounting checks.
Normal Daytona setup now has an explicit operator command to import a verified
The dedicated key recorded $0.000510742 for the hello and $0.004995065 for the
failed question. Including the earlier profile-11 failure ($0.000142518), its
observed total was $0.005648325 at that reconciliation. These are observed key
usage changes, not native per-request bills. No failed result has been regraded.
Diagnosis found that the runner did not select the ACP reasoning mode. The
pinned model's implicit Pi `medium` setting resolves to `high`; this behavior
also existed in Pi 0.84.2. Pi 1.0 exposes a genuine `low` level. Profile 13 carries
an explicit setting through configuration, transport, and durable identity,
and requires the native effective level to match before a prompt is sent.
It does not increase the timeout. The timed-out HTTP body was not captured,
so source-derived default mapping does not establish the cause of that failure.
Fresh qualification must use the new profile and exact final build.
Historical source `4c58da84fd86a0cd7bc1d952987b031786fc6b2b` passed full Runner
verification and normal Intel startup at 28.295 seconds under the original
30-second limit, plus all 48 native/ACP contract tests. The Intel result has
only 1.705 seconds of margin and does not establish broad cold-start reliability.
Its fresh Linux daemon, Pi pack, and image were built and inventoried; live
Daytona qualification remained pending. The public Mac installation reproduced
the complete Pi dependency closure using npm 11.19.0 from the verified Node
archive. None of these artifacts qualifies profile 13.
The same source's full repository check failed six stale test assertions and
an `ETXTBSY` binary-staging error; the downstream Grok check then lacked built
server output. Typecheck, token gates, and Product E2E typecheck/unit checks
passed. The stale assertions have targeted repairs. A Linux process owner was
not captured for `ETXTBSY`; two exact native fixtures later passed on ARM with
all owned daemon handles closed, which does not resolve the Linux failure.
The next complete source run retains bounded executable-holder evidence around
check boundaries. A later run on obsolete harness source was canceled by the
lead and is retained as incomplete, not successful verification.
Normal Daytona setup has an explicit operator command to import a verified
Linux companion into the installed server. It binds the trusted manifest to the
installed source, Pi profile, daemon and complete provider-pack inventory, then
uses the ordinary remote execution path without test-only binary or pack
overrides. Its 31 focused tests cover asynchronous bounded verification,
cancellation, existing-cache validation, contained paths and owned cleanup.
These tests do not establish live Daytona qualification or release publication.
Full repository typecheck, tests, token gates, Product E2E typecheck/unit checks,
and build passed on the earlier source `efe019a79f50440d7bd6c3bc6c75fb8f18953093`.
Its Runner verification also passed. These results are historical prerequisites;
profile 12 and the final installation changes still need their own verification.
installed source, Pi profile, daemon, and complete provider-pack inventory, then
uses ordinary remote execution without test-only binary or pack overrides.
The final installed import, image publication, and paid proof remain required.
The dedicated Pi test key has a $5 lifetime OpenRouter-credit limit. Its BYOK
charges are not included in that provider-enforced limit. Qualification therefore
also requires the reviewed operational policy verifying no configured BYOK
credentials, fresh account/key evidence, one paid case at a time, and usage
monitoring. The key's $5 reservation is counted once within the combined $100
campaign budget. Native price estimates are never substituted for provider bills.
charges are outside that provider-enforced limit, so qualification additionally
uses the reviewed no-BYOK operational policy, fresh account/key evidence, one
paid case at a time, and usage monitoring. The $5 reservation is counted once
within the combined $100 campaign budget. Native price estimates are never
substituted for provider bills.
The [Pi capability inventory](runner-pi-capabilities.md#historical-pi-10-candidate-2026-10-02-profile-v12)
records Pi 1.0's native interfaces, wrapper changes, and unused capabilities.
The comparison below remains the supported-surface map; older paid observations
retain their named historical profiles. Current Pi 1.0 paid Product, Runner
protocol, native controls, and Daytona qualification are still pending.
The [Pi capability inventory](runner-pi-capabilities.md#historical-pi-10-candidate-2026-10-02-profile-v13)
records native interfaces, ACP mappings, user surfaces, and explicit gaps.
The comparison below remains the supported-surface map; old observations retain
their exact historical profile identities. Final source checks and profile-13
local Product, Runner protocol, native-control, and Daytona qualification remain
pending.
Historical source checkpoint (2026-10-01): **Cursor v10, Copilot v12 and Pi v10
remain unqualified**. Copilot receipt v2 distinguishes original provider