feat: pi-agent wrapper

docs/guides/pi-agent-isolation.md

@@ -0,0 +1,99 @@
+# Pi Agent Isolation (two-repo setup)
+
+This guide documents the split setup where:
+
+- `m3ta-nixpkgs` provides reusable module logic.
+- `nixos-config` consumes it on specific hosts.
+
+## 1) In `m3ta-nixpkgs`
+
+Use:
+
+- Home Manager module: `coding.agents.pi`
+  - renders Pi config in user space (default path: `.pi/agent` => `~/.pi/agent`)
+- NixOS module: `m3ta.pi-agent`
+  - dedicated user/group (default `pi-agent`)
+  - state directory (default `/var/lib/pi-agent`)
+  - hardened execution via transient `systemd-run`
+  - host-side wrapper command (default `pi`)
+  - per-user allowlists via `hostUsers.<name>.projectRoots`
+  - host config sync into isolated runtime (default source `.pi/agent`)
+  - managed settings/env merge into isolated runtime
+
+## 2) In consumer repo (`nixos-config`)
+
+### Home Manager side
+
+Keep Pi config rendering enabled for your normal user:
+
+```nix
+coding.agents.pi = {
+  enable = true;
+  agentsInput = inputs.agents;
+  path = ".pi/agent";
+};
+```
+
+### NixOS host side (example: `m3-kratos`)
+
+Enable isolated wrapper execution:
+
+```nix
+m3ta.pi-agent = {
+  enable = true;
+  stateDir = "/var/lib/pi-agent";
+
+  hostUsers = {
+    m3tam3re = {
+      projectRoots = ["~/p" "~/work/private"];
+      # optional; defaults to wrapper.hostConfigPath
+      configPath = ".pi/agent";
+    };
+  };
+
+  settings = {
+    defaultProvider = "anthropic";
+    defaultModel = "anthropic/claude-sonnet-4";
+    quietStartup = true;
+  };
+
+  environment = {
+    PI_TELEMETRY = "0";
+  };
+
+  environmentFiles = [
+    "/run/secrets/pi-agent.env"
+  ];
+
+  wrapper = {
+    enable = true;
+    commandName = "pi";
+    hideDirectBinary = true;
+    hostConfigPath = ".pi/agent";
+  };
+};
+```
+
+## 3) Authorization model
+
+The wrapper uses a tightly scoped sudo rule:
+
+- authorized users may run only the privileged runner command
+- with `NOPASSWD`
+- no broad `NOPASSWD: ALL`
+
+## 4) Merge behavior
+
+At invocation time, isolated runtime files are built from:
+
+1. Host user Pi config (synced from source path, e.g. `~/.pi/agent`)
+2. Nix-managed settings/env (override host values)
+3. Environment files (appended after managed env attrs)
+
+This keeps user-authored Pi config available while allowing reproducible Nix overrides.
+
+## 5) Migration notes
+
+- If wrapper mode is canonical, remove direct `pi-coding-agent` from user package lists to reduce command-path ambiguity.
+- Rebuild host config and test from an allowlisted project path.
+- Validate `pi` process identity runs as `pi-agent`.

docs/guides/using-modules.md

@@ -157,6 +157,32 @@ m3ta.mem0 = {
 
 **Documentation**: [mem0 Module](../modules/nixos/mem0.md)
 
+#### `m3ta.pi-agent`
+
+Isolated Pi execution with a dedicated system user (`pi-agent` by default),
+a hardened runtime, and a host-side `pi` wrapper command.
+
+```nix
+m3ta.pi-agent = {
+  enable = true;
+  stateDir = "/var/lib/pi-agent";
+
+  hostUsers = {
+    m3tam3re = {
+      projectRoots = ["~/p" "~/work/private"];
+      configPath = ".pi/agent"; # optional
+    };
+  };
+
+  settings.defaultModel = "anthropic/claude-sonnet-4";
+  environment.PI_TELEMETRY = "0";
+  wrapper.commandName = "pi";
+  wrapper.hideDirectBinary = true;
+};
+```
+
+**Documentation**: [Pi Agent Isolation Guide](./pi-agent-isolation.md)
+
 ### Home Manager Modules
 
 #### `m3ta.ports`
@@ -255,6 +281,7 @@ Pi agent deployment from canonical TOML definitions.
 coding.agents.pi = {
   enable = true;
   agentsInput = inputs.agents;
+  path = ".pi/agent"; # default; can be changed
 };
 ```