---
status: resolved
parent: "[[070-pi-ui-flex-spacer-pi-patch-task]]"
blocked-by: []
resolved-at: "2026-08-01T08:35:00-04:00"
tags:
  - ticket/research
---

# Patched Pi packaging research

## Question

How should the flex-spacer Pi layout patch be packaged in this dotfiles flake so the ordinary `pi` command uses it after rebuild?

## Findings

The flex-spacer change is not an extension-only change.
Pi's interactive mode source adds TUI children directly in `packages/coding-agent/src/modes/interactive/interactive-mode.ts`: header, loaded resources, chat, pending messages, status, widgets above editor, editor, widgets below editor, and footer.
That is the layout stack the flex-spacer must change.
Source: `/nix/store/7dv5wnq7ncw0mrhv5cldj5v6lar7lis7-source/packages/coding-agent/src/modes/interactive/interactive-mode.ts`.

The installed Pi package is the nixpkgs `pi-coding-agent` package at version `0.82.1`.
Its nixpkgs derivation builds from the upstream GitHub tag `v0.82.1`, restores the generated model catalog from the published npm package, builds TypeScript workspace packages, and wraps `$out/bin/pi` with Nix-provided `ripgrep` and `fd` on `PATH` plus default telemetry/version-check environment variables.
Source: `/nix/store/bzc7kf828kg6zlan92766rb2inciclc4-source/pkgs/by-name/pi/pi-coding-agent/package.nix`.

The active installed wrapper confirms the nixpkgs wrapper shape.
`/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/bin/pi` prepends Nix-store `fd` and `rg` paths, sets `PI_SKIP_VERSION_CHECK` and `PI_TELEMETRY`, then execs `.pi-wrapped` inside the same package output.
Source: `/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/bin/pi`.

The current dotfiles Pi module uses Home Manager's `programs.pi-coding-agent` module.
It currently sets `enable`, `settings`, managed extension files, and managed prompt files, but does not override the Pi package.
Source: `modules/agents/pi/pi.nix`.

The Home Manager Pi configuration does expose a `package` option in this evaluated system.
A targeted eval of `home-manager.users.alexion.programs.pi-coding-agent` returned keys including `package`, and an `extendModules` eval setting `home-manager.users.alexion.programs.pi-coding-agent.package = pkgs.pi-coding-agent.overrideAttrs (...)` changed the evaluated package name to `pi-coding-agent-test-0.82.1`.
Source: `nix eval .#nixosConfigurations.neogaia.config.home-manager.users.alexion.programs.pi-coding-agent`; command verification in this research session.

The patch should therefore be applied by overriding `programs.pi-coding-agent.package`, not by installing a competing wrapper or copying a patched tree under home.
A package override keeps the ordinary `pi` command managed by Home Manager and preserves the nixpkgs wrapper behavior unless deliberately changed.
Sources: `modules/agents/pi/pi.nix`; `/nix/store/bzc7kf828kg6zlan92766rb2inciclc4-source/pkgs/by-name/pi/pi-coding-agent/package.nix`.

The safest patch point is source-level patching before the TypeScript build, not post-install editing of generated JavaScript.
The nixpkgs package builds from upstream TypeScript source and already runs the TypeScript build in `buildPhase`, so a `patches = [...]` or `postPatch` override can modify `packages/coding-agent/src/modes/interactive/interactive-mode.ts` and `packages/coding-agent/src/utils/tools-manager.ts` before compiled output is produced.
Source: `/nix/store/bzc7kf828kg6zlan92766rb2inciclc4-source/pkgs/by-name/pi/pi-coding-agent/package.nix`.

The tool lookup hardening belongs in the same package override if the layout patch already overrides Pi.
Upstream `tools-manager.ts` currently treats a local tool path as available if the file exists and treats `spawnSync(cmd, ["--version"])` as success whenever there is no spawn error, without requiring exit status `0`.
On NixOS this allowed an unusable generic Linux `~/.pi/agent/bin/fd` to mask the working Nix `fd` on `PATH`.
Source: `/nix/store/7dv5wnq7ncw0mrhv5cldj5v6lar7lis7-source/packages/coding-agent/src/utils/tools-manager.ts`.

A package override avoids the hardcoded-wrapper problem that a post-install copied package would create.
If we copied the already-built installed package manually, its `bin/pi` script would still contain hardcoded store paths to the original `.pi-wrapped` and original Nix `fd`/`rg` inputs.
Using `pkgs.pi-coding-agent.overrideAttrs` and the original derivation's `postFixup` lets Nix regenerate the wrapper for the patched output.
Sources: `/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/bin/pi`; `/nix/store/bzc7kf828kg6zlan92766rb2inciclc4-source/pkgs/by-name/pi/pi-coding-agent/package.nix`.

The likely dotfiles shape is:

```nix
let
  patchedPi = pkgs.pi-coding-agent.overrideAttrs (old: {
    patches = (old.patches or [ ]) ++ [ ./patches/pi-flex-spacer.patch ];
  });
in {
  home-manager.users.${user}.programs.pi-coding-agent = {
    enable = true;
    package = patchedPi;
    # existing settings unchanged
  };
}
```

If the patch is implemented with `postPatch` instead of a patch file, preserve any upstream `old.postPatch` first.
A patch file is preferable for reviewability because it makes the layout and tool-lookup changes explicit.

## Answer

Package the flex-spacer as a source-level patch to `pkgs.pi-coding-agent` and set `home-manager.users.${user}.programs.pi-coding-agent.package` to that overridden package in `modules/agents/pi/pi.nix`.

Do not package it as a separate extension.
Do not use the throwaway copied tree under `~/.local/share` for deployment.
Do not copy the built package output and edit generated JavaScript unless no source-level override works, because the installed wrapper hardcodes store paths and Nix's original derivation already knows how to rebuild and rewrap Pi correctly.

## Implementation notes

Create a reviewed patch file under the dotfiles Pi module, for example `modules/agents/pi/patches/pi-flex-spacer.patch`.
Patch these upstream source files:

- `packages/coding-agent/src/modes/interactive/interactive-mode.ts`
- `packages/coding-agent/src/utils/tools-manager.ts`

Then override the package in `modules/agents/pi/pi.nix` and assign it to `programs.pi-coding-agent.package`.

The implementation ticket `[[070-pi-ui-flex-spacer-pi-patch-task]]` should prefer this packaging plan.

## Limitations

This research verified the package option by evaluation and inspected the current nixpkgs package source.
It did not build the final override or run the patched source-level derivation.

The upstream Pi source path was realized with `nix build --no-link` during research because the fetched source store path had not yet been materialized.

## Citations

- `modules/agents/pi/pi.nix`.
- `/nix/store/bzc7kf828kg6zlan92766rb2inciclc4-source/pkgs/by-name/pi/pi-coding-agent/package.nix`.
- `/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/bin/pi`.
- `/nix/store/7dv5wnq7ncw0mrhv5cldj5v6lar7lis7-source/packages/coding-agent/src/modes/interactive/interactive-mode.ts`.
- `/nix/store/7dv5wnq7ncw0mrhv5cldj5v6lar7lis7-source/packages/coding-agent/src/utils/tools-manager.ts`.