nixpkgs/PLAN.md

# PLAN

## Context
- Target implementation is confirmed as `m3ta.pi-agent` (no container mode).
- You want a **fresh-from-scratch rewrite** of `modules/nixos/pi-agent.nix` and to ignore prior behavior as design baseline.
- Required behavior:
  - dedicated isolated Unix user/group for Pi (`pi-agent` defaults)
  - host UX stays `pi`
  - bypass prevention (wrapper should be the canonical executable path)
  - per-host-user project root policy (different roots per user)
  - no writable/access scope beyond isolated Pi home/state + explicitly allowed project roots
  - isolated environment must include user Pi config from HM (`modules/home-manager/coding/agents/pi.nix`) and support Nix-managed settings/env merging.
- Repo findings:
  - `modules/nixos/default.nix` + `flake.nix` already import/export `pi-agent` module.
  - `modules/home-manager/coding/agents/pi.nix` already renders Pi config files under a configurable relative path (`coding.agents.pi.path`, default `.pi/agent`).

## Approach
- Fully replace `modules/nixos/pi-agent.nix` with a new design centered on:
  1. **Dedicated runtime identity** (`user/group/createUser/stateDir`).
  2. **Policy-driven wrapper flow** (`pi` -> privileged runner -> isolated execution).
  3. **Per-user project allowlists** (cwd must be under roots assigned to invoking host user).
  4. **Config + env convergence**:
     - sync user HM Pi config directory (e.g. `~/.pi/agent`) into isolated state,
     - merge Nix-managed Pi settings into isolated `settings.json`,
     - merge Nix-managed env vars + env files into isolated runtime env source,
     - make merged results visible to the isolated runtime every invocation (without container recreation semantics).
  5. **Hard isolation defaults** with `systemd-run` sandboxing and explicit bind/read-write paths only for state + allowed projects.
- Keep wrapper command as `pi`, and avoid exposing direct package binary on PATH when wrapper mode is enabled.

## Files to modify
- `modules/nixos/pi-agent.nix` (full rewrite)
- `modules/nixos/default.nix` (only if import list changes)
- `flake.nix` (only if output export attrs change)
- `docs/guides/pi-agent-isolation.md` (update option model + merge behavior)
- `docs/guides/using-modules.md` (update examples/options)

## Reuse
- Module/user/service patterns:
  - `modules/nixos/mem0.nix`
  - `templates/nixos-module/default.nix`
- Pi config rendering contract to consume/sync:
  - `modules/home-manager/coding/agents/pi.nix` (`coding.agents.pi.path`, `settings.json`, `mcp.json`, agent docs)

## Steps
- [ ] Define the new `m3ta.pi-agent` option schema for fresh module behavior, including:
  - base runtime options (`package`, `binaryName`, `user`, `group`, `createUser`, `stateDir`),
  - wrapper controls (`enable`, `commandName`, runner name, hide-direct-binary behavior),
  - per-user policy map (allowed users and each user’s allowed project roots),
  - host-config sync knobs (source path relative/absolute),
  - Nix-managed settings/env options for merge.
- [ ] Implement new wrapper script:
  - identify invoking user,
  - validate user exists in policy map,
  - expand/resolve that user’s roots,
  - deny out-of-policy cwd,
  - escalate only to the dedicated runner.
- [ ] Implement new privileged runner script:
  - enforce root-only execution,
  - resync host Pi config into isolated config dir,
  - merge managed settings into isolated settings file,
  - merge managed env + env files into isolated env file/export source,
  - prepare deterministic project mount aliases under isolated home,
  - launch Pi through hardened transient `systemd-run` unit as isolated user.
- [ ] Apply hardening policy in execution profile:
  - `ProtectSystem=strict`, `ProtectHome=yes`, `NoNewPrivileges=yes`,
  - explicit `ReadWritePaths` limited to state + mounted allowed projects,
  - bounded runtime PATH and writable tool/cache locations under `stateDir`.
- [ ] Add assertions for misconfiguration (e.g., empty per-user roots, wrapper enabled without authorized users).
- [ ] Add tightly scoped sudoers rule for runner command only.
- [ ] Ensure bypass prevention in packaging/PATH behavior when wrapper mode is enabled.
- [ ] Update docs with new option examples (per-user roots + settings/env merge + HM sync expectations).

## Verification
- Static/eval:
  - `nix flake check`
  - host config eval/build with new module options.
- Policy checks:
  - authorized user in authorized root: succeeds
  - authorized user outside authorized root: denied
  - unauthorized user: denied
- Isolation checks:
  - runtime identity is isolated service user (`pi-agent`)
  - no unintended write access outside `stateDir` + allowed project binds
  - direct binary bypass unavailable when wrapper mode is enabled
- Merge checks:
  - HM-rendered Pi files are present in isolated config dir
  - Nix-managed settings are merged into effective isolated `settings.json`
  - env values from declarative attrs + env files are present in isolated runtime environment.

## Open questions
- None.

## Resolved decisions
- Merge precedence is confirmed as:
  1) synced host Pi config/env,
  2) Nix-managed settings/env override synced values,
  3) wrapper/runtime shell env does not implicitly override managed values.
- Per-user host config source defaults to `.pi/agent` for all users, with optional per-user override support in the policy map.