Upgrade Pi coding agent to 1.0.0 in the workspace image (#3542)

[mcdonc]

Summary

Bump the workspace image's sha512-pinned Pi coding agent tarball from 0.99.2 to 1.0.0 (PI_AGENT_VERSION / PI_AGENT_SHA512 in src/containers/workspace/Dockerfile; hash re-derived from the registry's own dist.integrity and verified against the fetched tarball).

Pi 1.0 runs its TUI fullscreen by default, which replaces the web terminal's normal scrollback with pi's own viewport. The provisioning already protects that scrollback twice over (theme: "dark" #3535, quietStartup: true #3537), so klangk-setup-pi.py now writes tuiMode: "regular" and backfills it for existing settings.json files (explicit user overrides are preserved, as with the other provisioned keys). Users who want fullscreen can set tuiMode: "fullscreen" in their own settings.

Verified the builtin extensions' API surface is unchanged in 1.0.0 — getAgentDir, CustomEntry, EntryRenderOptions, ExtensionCommandContext, Theme from @earendil-works/pi-coding-agent and Container/Text from @earendil-works/pi-tui (now 1.0.0) all still exist with the same export shapes; the extensions need no changes.

Closes #3542.

Changes

• src/containers/workspace/Dockerfile — pin 1.0.0 + refreshed sha512.
• src/containers/workspace/klangk-setup-pi.py — provision tuiMode: "regular" (new settings + backfill), with rationale comment.
• src/containers/workspace/builtin-extensions/startup-header.ts — comment references pi 1.0.0.
• src/klangk/klangkd-tests/tests/test_setup_pi.py — cover tuiMode provisioning, backfill, and user-override preservation.
• docs/features/ai-coding-harnesses.md, docs/changes.md — document the provisioned setting and the upgrade.

[mcdonc]

Fresh-eyes review

Review ran against 935c116; the two nits (changelog sentence count, docs placement) are addressed in b5e356b.

Review: PR #3543 — pi agent 0.99.2 → 1.0.0

Verified correct (the ship-sinking risks)

SHA-512 pin — correct, verified two independent ways. Fetched tarball: sha512sum = fc5b5bc6…440ad33, matches src/containers/workspace/Dockerfile:21. Registry dist.integrity (sha512-/FtbxoSQ…), base64→hex decodes to the identical hex string. Also confirmed the old 0.99.2 pin (e91d416…) still matches its tarball, so the pin history isn't rewritten.

Extension API surface — no break. Checked every symbol and call the 4 builtin extensions + 5 feature extensions use against the extracted 1.0.0 tarball (/tmp/pi100):

• getAgentDir, CustomEntry, EntryRenderOptions, ExtensionAPI, ExtensionCommandContext, Theme all still exported (dist/index.d.ts:2,8,21,37).
• pi-tui 1.0.0 (pinned via npm-shrinkwrap.json) still exports Container (dist/index.d.ts:31) and Text with the same (text?, paddingX?, paddingY?) constructor — matches startup-header.ts:110-114.
• Theme.fg(color, text) unchanged, and both color tokens used (mdHeading, dim) are still in the ThemeColor union (dist/modes/interactive/theme/theme.d.ts:15).
• The sneaky one: getCommands() returns SlashCommandInfo[] with source: "extension"|"prompt"|"skill" (dist/core/slash-commands.d.ts:2-6) — the filter on command.source at startup-header.ts:41 still works. (0.99.2 identical — I diffed ToolDefinition and RegisteredCommand between versions; zero drift.)
• Feature extensions importing @sinclair/typebox (pi renamed the dep to typebox) still work: pi 1.0.0's loader compat-aliases @sinclair/typebox → its bundled typebox (dist/core/extensions/loader.js:80-82, virtual-modules.js:17-19).
• No /header builtin command in 1.0.0 (BUILTIN_SLASH_COMMANDS has no header) — no collision with the extension's registered command; the "no API to re-run its own renderer" comment at startup-header.ts:11 still holds.

Carried-forward assumptions — all still valid in 1.0.0: PI_OFFLINE and PI_SKIP_VERSION_CHECK (used per #3530/#3533), hideThinkingBlock, theme "dark", quietStartup: true, defaultProvider/defaultModel/extensions/skills/prompts settings keys, api: "openai-completions" (still a KnownApi in pi-ai 1.0.0 dist/types.d.ts:15), the !command apiKey convention, and Node engines (>=22.19.0, unchanged vs 0.99.2; base image ships Node 26 per Dockerfile.base:68-70).

tuiMode decision — sound. tuiMode is a real settings.json key in 1.0.0 (docs/settings.md:94, read at dist/core/settings-manager.js:951), values "regular" | "fullscreen", default "fullscreen" — confirmed by pi's own CHANGELOG ("Changed the default TUI mode to fullscreen"). The regular-mode pin is the documented upstream escape hatch and matches the web-terminal/tmux scrollback rationale in docs/features/terminal.md.

Supply chain — unchanged. Same curl → sha512sum -c → npm install -g /tmp/pi-agent.tgz flow, no new post-install steps; Dockerfile.fips layers on this image and inherits the bump. test_supply_chain_pins.py: 19 passed. test_setup_pi.py: 15 passed. No stale 0.99 references outside historical changelog entries. Xenon unaffected (src/containers/ isn't in the graded set; no new branches anyway).

Findings

Nit 1 — changelog entry is 5 sentences (docs/changes.md:2331-2338). AGENTS.md caps entries at 2–4 sentences; counting the bold lead this is 5, and the sibling pi-upgrade entry (#3511) is 3. Drop or merge one sentence — the supply-chain one is the weakest candidate (no operator action, restates what the supply-chain docs already say), though it does mirror #3511's wording, so keeping it is defensible.

Nit 2 — docs placement (docs/features/ai-coding-harnesses.md:52-54). The tuiMode: "regular" note is appended to the startup-header extension bullet, but tuiMode is a general provisioning setting with no connection to /header. A reader skimming extension descriptions gets the fullscreen/scrollback fact buried in the wrong bullet. Suggestion: split into its own sentence after the bullet list, next to where provisioning is described ("Extensions are installed at image build time…").

Question — delete-key path for fullscreen seekers. ensure_settings_keys (klangk-setup-pi.py:98-116) re-adds a deleted tuiMode on every login, so a user who wants pi 1.0's new fullscreen default and expresses that by deleting the key silently gets regular restored; only setting tuiMode: "fullscreen" sticks. The changelog sentence ("set tuiMode to fullscreen") is accurate, and this matches the established theme/quietStartup backfill tradeoff (#3535/#3537) — just confirm the delete-key revert is intended, since unlike those keys, "absent" now has a meaningful upstream default.

Observation (pre-existing, out of scope): ensure_settings_keys never backfilled hideThinkingBlock for users provisioned before that key existed; this PR touches exactly that defaults dict and leaves the asymmetry. Not this PR's job to fix.

Verdict

No blocking or important issues. The pin is right, the API surface is genuinely unchanged (including the non-obvious @sinclair/typebox alias and SlashCommandInfo.source traps), the product decision is documented upstream as the intended escape hatch, and tests/docs/changelog cover it. Two nits and one confirm-intended question above — mergeable after those are addressed or consciously waved off.

[mcdonc]

3D dependency graph (self-contained HTML)

• Render in browser
• Gist source

The page is fully self-contained: save it from either link and it opens offline. GitHub serves the raw gist as plain text, so the source link downloads; the render link views.

[mcdonc]

Created backport PR for stable/2.0:

• Upgrade Pi coding agent to 1.0.0 in the workspace image (#3542) #3544 with remaining conflicts!

Please cherry-pick the changes locally and resolve any conflicts.

git fetch origin backport-3543-to-stable/2.0
git worktree add --checkout .worktree/backport-3543-to-stable/2.0 backport-3543-to-stable/2.0
cd .worktree/backport-3543-to-stable/2.0
git reset --hard HEAD^
git cherry-pick -x 8802f452a95b3846a0b8382cb99656bb91845517