---
status: done
claimed-by: "019fba91-eabf-76ae-b086-a37ac061d6e8"
claimed-at: "2026-07-31T21:17:55-04:00"
completed-at: "2026-07-31T21:18:12-04:00"
parent: "[[002-pi-subagents-map]]"
blocked-by: []
tags:
  - ticket/task/afk
---

# Dotfiles deployment seam

## Question

Define the dotfiles deployment seam for the new Pi subagent extension, including development placement, flake-managed promotion, configuration files, and verification commands needed before implementation starts.

## Result

The extension should be developed as a Pi extension under `modules/agents/pi/extensions/subagents/` and deployed by the existing Home Manager file link from `modules/agents/pi/pi.nix` to `~/.pi/agent/extensions`.
Finished work must be promoted through the dotfiles module before it counts as deployed.
Direct files under `~/.pi/agent/extensions` are acceptable only for throwaway development or local experiments.
This matches the repository gotcha that flake-managed Pi extension, prompt, and skill directories may be written directly for experiments but durable deployment must go through the dotfiles module.
Source: `/home/alexion/wrk/dotfiles/AGENTS.md`.

No install step should be part of the implementation plan without explicit user consent.
The durable path should avoid `pi install`, npm package installation, or git package installation for version one.
If runtime dependencies become unavoidable, the implementation spec must pause for consent and then model the dependency declaratively in Nix rather than asking Pi to install it interactively.
Source: user constraint and Pi package security docs in `/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/docs/packages.md`.

## Current Pi deployment shape

`modules/agents/pi/pi.nix` enables `programs.pi-coding-agent` through Home Manager.
It writes Pi settings with `defaultProvider`, `defaultModel`, `defaultThinkingLevel`, theme, and telemetry choices.
It force-manages `~/.pi/agent/settings.json` but intentionally leaves login credential state unmanaged.
Source: `modules/agents/pi/pi.nix`.

The same module recursively links `modules/agents/pi/extensions` to `~/.pi/agent/extensions`.
It also recursively links `modules/agents/pi/prompts` to `~/.pi/agent/prompts`.
Source: `modules/agents/pi/pi.nix`.

The current `modules/agents/pi/extensions` directory contains only `.gitkeep`.
That means a new extension can be added there without colliding with existing Pi extension code.
Source: `find modules/agents/pi -maxdepth 3 -type f` during this task.

Pi's extension docs say global extensions are auto-discovered from `~/.pi/agent/extensions/*.ts` and `~/.pi/agent/extensions/*/index.ts`.
Project-local extensions are auto-discovered from `.pi/extensions/*.ts` and `.pi/extensions/*/index.ts` after project trust.
Source: `/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/docs/extensions.md`.

Pi can hot-reload auto-discovered extension locations with `/reload`.
Source: `/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/docs/extensions.md`.

## Proposed repository layout

Use this layout for version one:

```text
modules/agents/pi/extensions/subagents/
├── index.ts
├── agents.ts
├── config.ts
├── runner.ts
├── supervisor.ts
├── status.ts
├── types.ts
└── ui.ts
```

`index.ts` should be the extension entry point and should export the default Pi extension factory.
`agents.ts` should load and validate named agent definitions.
`config.ts` should resolve extension settings and default policy.
`runner.ts` should implement the subprocess RPC `ChildRunner`.
`supervisor.ts` should own child records, lifecycle, cancellation, timers, and concurrency.
`status.ts` should define parent-session entries and renderable status data.
`types.ts` should hold shared TypeScript types.
`ui.ts` should isolate optional TUI/RPC status and confirmation helpers.

Keep filenames lowercase.
This follows the user's global filename preference and the repository convention.
Source: `/home/alexion/.pi/agent/AGENTS.md` and `/home/alexion/wrk/dotfiles/AGENTS.md`.

Do not add a `package.json` unless implementation discovers an unavoidable external runtime dependency.
Pi extensions can import Pi-provided packages such as `@earendil-works/pi-coding-agent`, `@earendil-works/pi-ai`, `@earendil-works/pi-tui`, and `typebox` directly.
Source: `/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/docs/extensions.md`.

## Agent definition deployment seam

The extension should load user-level agent definitions from `~/.pi/agent/agents/` and project-level definitions from `.pi/agents/` after trust.
Because the current dotfiles module does not link `modules/agents/pi/agents`, add this managed directory when real agent definitions are committed.
The module should link it recursively to `~/.pi/agent/agents` in the same style as extensions and prompts.

Proposed durable layout:

```text
modules/agents/pi/agents/
└── .gitkeep
```

Proposed Nix addition when needed:

```nix
"${piDir}/agents" = {
  source = ./agents;
  recursive = true;
};
```

The initial extension should not ship opinionated agent definition files.
The directory can contain `.gitkeep` only until the user intentionally adds named agents.
This satisfies the constraint that named agents, prompts, and policy belong in Pi config rather than the neutral extension.

## Settings seam

Do not add extension-specific settings to `programs.pi-coding-agent.settings` until the implementation schema is finalized.
When settings are needed, keep them under a clearly namespaced key such as `subagents` only if Pi preserves unknown settings for extension consumption.
If Pi's typed settings reject unknown keys, store extension config in a separate user-level file such as `~/.pi/agent/subagents.json` and manage it through Home Manager `home.file`.
The implementation spec must verify Pi's settings parser behavior before choosing this.

Recommended initial defaults should live in extension code and be neutral:

- Runtime: `subprocess-rpc`.
- Max concurrent children: `2` or `3`.
- Default context: unresolved by [[022-pi-subagents-context-modes-grill]].
- Project agents: disabled until project trust is confirmed.
- Project extension inheritance: disabled.
- Nested children: disabled.
- Tool policy: minimal and explicit.

Do not encode opinionated subagent types in settings.
Do not add Herdr settings to the Pi extension seam.
Herdr remains an optional later adapter and should not shape the core deployment.

## Development workflow

For quick experiments, it is acceptable to copy or create a throwaway extension directly under `~/.pi/agent/extensions/subagents/`.
That is not durable and may be overwritten or hidden by Home Manager activation.
Source: `/home/alexion/wrk/dotfiles/AGENTS.md` gotcha about flake-managed Pi directories.

For implementation work that should persist, edit `modules/agents/pi/extensions/subagents/` in the repository.
Then reload Pi or rebuild Home Manager depending on whether the current session sees the repository path through the existing symlink.
Because `modules/agents/pi/pi.nix` recursively links the entire `extensions` directory, editing the source tree should normally be enough for `/reload` in the running Pi session to see the change.
A rebuild is required to verify clean-machine deployment.

Use `pi -e ./path.ts` only for quick tests of an isolated file.
The Pi docs identify `-e` as a quick-test path and say auto-discovered global or project locations are the right placement for `/reload`.
Source: `/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/docs/extensions.md`.

## Verification commands

Use these checks before implementation starts:

```bash
nix eval .#nixosConfigurations.neogaia.config.modules.agents.pi.enable
```

Expected result: `true`.
This verifies the Pi module is enabled for the current host.

```bash
nix eval .#nixosConfigurations.neogaia.config.home-manager.users.alexion.home.file.'"/home/alexion/.pi/agent/extensions"'.source
```

Expected result: a Nix store path sourced from `modules/agents/pi/extensions` after evaluation.
This verifies the deployment link remains declared.

```bash
nix eval .#nixosConfigurations.neogaia.config.home-manager.users.alexion.home.file.'"/home/alexion/.pi/agent/prompts"'.source
```

Expected result: a Nix store path sourced from `modules/agents/pi/prompts`.
This is a control check matching the existing prompt link.

After adding `modules/agents/pi/agents`, add and run this check:

```bash
nix eval .#nixosConfigurations.neogaia.config.home-manager.users.alexion.home.file.'"/home/alexion/.pi/agent/agents"'.source
```

Expected result: a Nix store path sourced from `modules/agents/pi/agents`.

Use the repository's primary verification seam before merging implementation:

```bash
nix flake check
```

The project gotcha says `nix flake check` builds `checks.x86_64-linux.<host>` and is the primary build/verify seam for any host.
Source: `/home/alexion/wrk/dotfiles/AGENTS.md`.

For cheap targeted evaluation during implementation, use `nix eval .#nixosConfigurations.neogaia.config...` rather than committing speculative host enablement.
Source: `/home/alexion/wrk/dotfiles/AGENTS.md`.

## Runtime verification after implementation

Use these manual checks after the extension exists:

```bash
pi --mode rpc --no-session
```

Then send a minimal JSONL prompt and confirm the process speaks RPC.
This verifies the child runtime target independently of the extension.
Source: Pi RPC docs in `/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/docs/rpc.md`.

Inside Pi, run `/reload` after editing the managed extension source and confirm the extension reloads without restarting Pi.
This verifies the global extension discovery path.
Source: Pi extension docs in `/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/docs/extensions.md`.

After adding a status renderer, spawn a trivial read-only child and verify these properties:

- Parent transcript receives a compact status entry.
- Child transcript or session remains separate.
- Cancelling the parent tool call cancels the child.
- The child exits or is killed on timeout.
- No project-local agent definition loads before project trust.
- No Herdr-specific behavior is required.

## Files to change during implementation

Expected durable changes:

- `modules/agents/pi/extensions/subagents/index.ts`.
- `modules/agents/pi/extensions/subagents/*.ts` helper files.
- `modules/agents/pi/agents/.gitkeep` if the managed user-agent directory is introduced.
- `modules/agents/pi/pi.nix` only if the agents directory or extension config file is linked.

Avoid these changes unless explicitly justified:

- Do not edit `~/.pi/agent` directly for durable deployment.
- Do not modify generated Home Manager output.
- Do not install Pi packages with `pi install`.
- Do not add Herdr-specific config to the Pi module for version one.
- Do not add named opinionated subagents to the neutral extension.

## Open implementation questions

The implementation spec still needs decisions from [[021-pi-subagents-config-boundary-grill]] and [[022-pi-subagents-context-modes-grill]].
The status UI details still depend on [[023-pi-subagents-status-ui-prototype]].
This deployment seam is therefore ready for implementation planning but not by itself sufficient to start coding the extension.