@coralai/nps-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Coral / wykj
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,459 @@
+# nps-cli — Vision Doc (rev 5, aligned with CEO plan)
+
+> **Status:** v0.1.0-alpha.0 skeleton landed; engineering plan rev 5 ready to implement.
+> Last updated 2026-05-14 by Coral + Claude after CEO + Eng review cycles.
+
+> **Authoritative engineering plan:**
+> `~/.gstack/projects/coral-jarvis-skills/ceo-plans/2026-05-14-nps-cli-v0-1.md` (rev 5)
+>
+> This README captures the **what + why**. The CEO plan captures the **how + effort**.
+
+---
+
+## 1. What is nps-cli
+
+**nps** is a **Linux-only local daemon** that hosts ephemeral Claude Code agent processes accessible via IM (Matrix DM in v0.1). Each agent is defined by a **profile** — a directory with its own personality, skills, and an external workspace pointer. Per message, nps spawns a Claude binary, dispatches the message, persists the result, and stops — no long-lived per-channel cache (codex F2 design lesson from rev 3 → rev 4 pivot).
+
+Think of it as:
+
+- **Discord-bot framework**, but: agent-first, ephemeral-per-message, project-skill-scoped.
+- **openclaw**, but: agent profile abstraction with workspace routing + safe session resume.
+- **sps-cli**, but: NOT a worker pipeline. Conversational, IM-driven.
+
+The core runtime primitive is **`@coralai/claude-code-agent`** (Phase 1 package, v0.2+). nps-cli is the first true consumer of its public `ClaudeCodeAgent` class.
+
+---
+
+## 2. Why nps-cli (the gap)
+
+After Phase 1, `@coralai/claude-code-agent` exists as a clean library. Beyond proving its API, the actual product value:
+
+- Coral wants a **personal AI presence** reachable through Matrix DM, backed by skills he can iterate locally.
+- Different conversational contexts (work, finance, study) deserve **different agents** with their own personalities and skills.
+- sps-cli is a **build pipeline**, not a conversational front-end. Two different products with one shared runtime.
+
+**v0.1 is a validation vehicle, not a finished product.** It proves three things before any platform feature is built on top:
+
+1. **Workspace routing** — agent persona/skills at A, task workspace at B, never conflated.
+2. **Safe session resume** — `resumeSession` works AND has compatibility invalidation done BEFORE resume.
+3. **One real transport loop** — Matrix DM in, reply out, no crash, no leaked process, with event-id dedupe.
+
+Everything not directly serving those goals is deferred.
+
+---
+
+## 3. Relationship to other projects
+
+```
+┌───────────────────────────────────────────────────────────────┐
+│                          nps-cli                              │
+│  (this project — Linux daemon + Matrix DM gateway + profiles) │
+└─────────────────────────────┬─────────────────────────────────┘
+                              │
+                              ▼
+       @coralai/claude-code-agent ^0.2.0 (Phase 1 package)
+       • v0.1: start / stop / prompt / cancelAll
+       • v0.2: + start({ resumeSession }) ← nps prereq, shipped
+                              │
+                              ▼
+              @agentclientprotocol/sdk ^0.21
+                              │
+                              ▼
+                claude-agent-acp shim 0.33.1
+                              │
+                              ▼
+                claude binary (OAuth subscription)
+```
+
+- **sps-cli** stays a separate consumer of `@coralai/claude-code-agent`. nps-cli is a sibling, not a fork.
+- **Multi-vendor LLM**: NOT via an `LLMBackend` abstraction inside nps-cli (decision D2). Instead, profiles can point `ANTHROPIC_BASE_URL` at an API-compat proxy (e.g. CLIProxyAPI, litellm) — the claude binary still thinks it's talking to Anthropic. Backend abstraction = zero code in nps-cli.
+
+---
+
+## 4. Platform target
+
+**Linux only in v0.1.** The implementation depends on systemd user units, journald for log aggregation, `flock` for file locking, Unix domain sockets, and `loginctl enable-linger` for user-mode service supervision. macOS launchd and Windows support are deferred to v0.1.x.
+
+---
+
+## 5. User scenario (concrete)
+
+Coral runs `nps daemon start` as a systemd user service. He has three agent profiles:
+
+```
+~/.nps/
+├── config.yaml                    # global: Matrix homeserver, admin user ids
+├── bindings.yaml                  # channel → profile mapping (CLI-managed in v0.1)
+└── agents/
+    ├── work-companion/
+    │   ├── nps.yaml               # workspace: /home/coral/jarvis-skills, env: ANTHROPIC_BASE_URL=...
+    │   ├── CLAUDE.md              # "你是 Coral 的工作助手..."
+    │   └── .claude/skills/
+    │       ├── code-review/SKILL.md
+    │       └── architecture-sketch/SKILL.md
+    ├── personal-finance/
+    │   ├── nps.yaml               # workspace: /home/coral/.finance, env: ...
+    │   ├── CLAUDE.md
+    │   └── .claude/skills/...
+    └── study-buddy/
+        └── ...
+```
+
+In Matrix DM with `@nps-work-companion:matrix.org`, Coral types "review the latest PR on jarvis-skills." nps daemon:
+
+1. Receives the message (Matrix event with `event_id`).
+2. Checks event-id dedupe (drop if already processed).
+3. Looks up channel binding → `work-companion`.
+4. Computes `compatHash` from profile artifacts.
+5. Checks stored hash; if mismatch → drop stored sessionId (fresh start); else use it for resume.
+6. Spawns `ClaudeCodeAgent({ cwd: /home/coral/jarvis-skills, env: profile.env })`.
+7. `agent.start({ resumeSession: validId })` — or no resume on fresh start.
+8. `agent.prompt(text)` — claude does its work in the actual repo.
+9. Atomically persists `{ sessionId, compatHash, lastEventId }`.
+10. `agent.stop()` — process gone, baseline RAM.
+11. Sends reply (Matrix `m.text` final, no streaming in v0.1).
+
+Tomorrow Coral restarts the daemon. Next message in the DM resumes from the stored sessionId because `compatHash` matches (no profile edits).
+
+---
+
+## 6. Architecture
+
+### 6.1 Process model
+
+Single Node.js daemon on Linux. Spawns a fresh Claude binary per message, then exits.
+
+```
+nps daemon (one Node process)
+  ├── ProfileRegistry      — scan + chokidar watch ~/.nps/agents/
+  ├── BindingsLoader       — atomic read of ~/.nps/bindings.yaml
+  ├── DispatchPipeline     — dedupe → lookup → compat check → resume/fresh → prompt → persist → stop → send
+  ├── MatrixGateway        — DM-only client (unencrypted, final-only replies, event-id dedupe)
+  ├── SessionStore         — atomic-write JSON per channel: { sessionId, compatHash, lastEventId }
+  ├── ControlSocket        — JSON-RPC 2.0 on Unix socket + PID file + stale-socket detection
+  └── pino logger          — stdout → journald
+```
+
+**Notably absent** (deferred to v0.2+ if dogfooding shows need):
+- No AgentSupervisor (no per-channel cache)
+- No idle eviction (nothing to evict)
+- No health auto-restart of agents (ephemeral processes can't hang)
+- No LLMBackend abstraction (D2)
+
+### 6.2 DispatchPipeline — corrected order (codex F1, F11)
+
+```
+on MatrixGateway emits Message{ channelId, eventId, text, sender }:
+  1. SessionStore.hasSeenEvent(eventId)?         → silent drop on duplicate
+  2. BindingsLoader.lookup(channelId) → profile  → /help reply on miss
+  3. Compute currentCompatHash from profile artifacts (spec below)
+  4. SessionStore.get(channelId) → { storedHash?, sessionId? }
+  5. ── COMPAT CHECK BEFORE RESUME ──            ← codex F1: NOT after
+       if storedHash !== currentCompatHash:
+         resumeId = undefined                    # fresh start
+         IM reply hint: "session reset (config changed)"
+       else:
+         resumeId = sessionId
+  6. agent = new ClaudeCodeAgent({ cwd: profile.workspace, env: profile.env, ... })
+  7. await agent.start({ resumeSession: resumeId })
+  8. result = await agent.prompt(text)
+  9. ── PERSIST BEFORE SEND ──                   ← codex F11
+       await SessionStore.atomicWrite(channelId, {
+         sessionId:  result.sessionId,
+         compatHash: currentCompatHash,
+         lastEventId: eventId,
+       })
+ 10. await agent.stop()
+ 11. await gateway.sendReply(channelId, result.text)  (retry once on transient failure)
+```
+
+### 6.3 compatHash specification (codex F3, F4)
+
+```
+Inputs (in canonical order, each ending with separator "\n--SEP--\n"):
+  1. profile.yaml             — yaml.dump with sorted keys, LF line endings
+  2. CLAUDE.md                — utf-8, LF line endings
+  3. skills/*.SKILL.md        — sorted by lexicographic filename
+  4. claude-code-agent npm version
+  5. claude binary version    — `claude --version` cached at daemon boot
+  6. claude-agent-acp version — `claude-agent-acp --version` cached at boot
+
+Algorithm:
+  sha256(canonical_bytes)
+
+Edge cases:
+  - Missing file       → include literal "<MISSING>" + path marker
+  - Symlinks           → resolve to target's content
+  - File read error    → throw COMPAT_HASH_FAILED, do NOT silently fresh-start
+  - Binary missing on boot → daemon refuses to start with actionable error
+
+NOT in hash (deliberately):
+  - workspace directory contents (workspace is task layer, not identity layer)
+  - .claude/settings.json (per-run preference, not agent identity)
+```
+
+### 6.4 Atomic write contracts (codex F7, F8)
+
+**bindings.yaml** (CLI-only writer):
+1. CLI acquires `~/.nps/.bindings.lock` (file lock).
+2. Reads current bindings.yaml.
+3. Mutates in-memory.
+4. Writes to `bindings.yaml.tmp` mode 0600.
+5. `rename(2)` for atomic replace.
+6. Releases lock.
+
+Daemon reader retries on transient `EBUSY` (max 3 attempts).
+
+**SessionStore** (daemon writer):
+- File per channel: `~/.nps/state/<channelId>.json` mode 0600.
+- Write → `.tmp` → `fsync` → `rename`.
+- Corrupt JSON on read → log warn + treat as empty (fresh start).
+
+**Audit log**:
+- `~/.nps/audit.jsonl` mode 0600, schema `{ v: 1, ts, sender, transport, channel, command_or_event, decision, profile? }`.
+- Rotation at 50MB → atomic rename to `.0`; shift `.0..3` up; delete `.4`. Retention 5 × 50MB = 250MB max.
+- ENOSPC → log `[CRITICAL] audit log unavailable` via pino, daemon continues.
+
+---
+
+## 7. Configuration model
+
+### 7.1 Global config (`~/.nps/config.yaml`)
+
+```yaml
+daemon:
+  controlSocket: ~/.nps/daemon.sock
+  pidFile: ~/.nps/daemon.pid
+  logLevel: info
+  adminUserIds:
+    - matrix:@coral:matrix.org
+
+im:
+  matrix:
+    homeserver: https://matrix.org
+    user: '@coral:matrix.org'
+    accessToken: ${MATRIX_TOKEN}      # env var indirection supported
+```
+
+### 7.2 Per-agent profile (`~/.nps/agents/<name>/`)
+
+```
+<name>/
+├── nps.yaml         # profile metadata (workspace, env, recording, idle settings)
+├── CLAUDE.md        # personality / rules (read by claude binary natively)
+└── .claude/skills/
+    └── <skill>/SKILL.md
+```
+
+`nps.yaml` schema:
+
+```yaml
+workspace: /home/coral/jarvis-skills   # SINGULAR — exactly one path per profile (D3=A)
+                                       # claude binary cwd; need multiple? create multiple profiles.
+
+env:                                   # passed through to claude binary via AgentOptions.env
+  ANTHROPIC_BASE_URL: https://my-proxy.example/anthropic    # optional API-compat proxy
+  # ANTHROPIC_API_KEY: ${MY_KEY}       # optional; omit to use OAuth subscription
+
+recording: ~/.nps/recordings/work-companion.jsonl   # optional, ClaudeCodeAgent recording
+
+permissionMode: auto                   # auto | readonly | manual
+```
+
+**Skill loading is free**: claude binary reads `cwd/CLAUDE.md` + `cwd/.claude/skills/` natively. But here `cwd = workspace` (task layer), so we set `CLAUDE.md` + skills INSIDE the profile dir AND we set workspace as cwd. Solution: nps daemon **copies / symlinks** profile's CLAUDE.md + .claude/skills/ into the workspace before spawn? Or: claude binary supports a separate `--system-prompt-file` flag? **TBD in M-WS implementation.**
+
+### 7.3 Channel bindings (`~/.nps/bindings.yaml`)
+
+```yaml
+matrix:
+  '!abc123:matrix.org': work-companion
+  '!def456:matrix.org': personal-finance
+```
+
+**CLI-managed only in v0.1** (codex F5 dodge — daemon doesn't write):
+```
+nps bind add <channel-id> <profile>
+nps bind remove <channel-id>
+nps bind list
+```
+
+IM `/bind /unbind /persona /reset` deferred to v0.1.x.
+
+---
+
+## 8. v0.1 milestones
+
+See CEO plan rev 5 for "done when" criteria + effort estimates. Summary:
+
+```
+PROTOTYPE GATES (parallel, can run before main impl):
+  M0    Lifecycle gate         — 3 concurrent claude sessions, distinct sessionIds, no auth collision (1-2d)
+  M0a   Resume gate            — resume sessionId, history retained, cleanly stop (0.5d)
+  M5a   Matrix transport spike — DM detect, encrypted-room refuse, send msg (0.5-1d)
+  M-WS  Workspace routing      — singular workspace per profile, agent gets correct cwd (1d)
+
+LANE A (daemon core, sequential):
+  M1  Daemon + control socket + JSON-RPC + PID file        (2-3d)
+  M2  ProfileRegistry (scan + chokidar watch)              (1d)
+  M3  BindingsLoader (atomic read + retry-on-EBUSY)        (1d)
+  M4  DispatchPipeline (corrected order, codex F1+F11)     (2d)
+  M6  SessionStore + compatHash + lastEventId dedupe       (2d)
+
+LANE B (gateway, after M5a + M6):
+  M5b Matrix gateway production (final-only, dedupe, reconnect backoff)  (2-3d)
+
+LANE C (CLI + ops, parallel with A):
+  M7  nps CLI (agent/daemon/bind subcommands)              (2d)
+  M8  Slash commands (/help open, /status admin only)      (1d)
+  M10 Boot runtime check (claude + shim presence)          (0.5d)
+  M11 systemd user unit + install-service                  (1-1.5d)
+  M12 Audit log (rotation + 0600 + schema v=1)             (1.5d)
+  M13 Structured logs (pino → journald)                    (0.5d)
+```
+
+**Effort total**: 18-23 human-days + 20% buffer = **22-28 human-days** (3-4.5 CC-days, 3-5 weeks calendar).
+
+### Slash command contract (minimal — D6=A, D7-resolved)
+
+| Command | Args | Side effect | Auth |
+|---------|------|-------------|------|
+| `/help` | — | Reply with command list + binding info | **Open** (any sender, including unbound DM first message) |
+| `/status` | — | Reply with profile, lastActivity, sessionId presence | **Admin only** |
+
+`/bind /unbind /reset /persona` → CLI only in v0.1.
+
+---
+
+## 9. Hard prerequisite
+
+**`@coralai/claude-code-agent` v0.2** — **shipped 2026-05-14**. Provides `start({ resumeSession?: string })`. nps-cli depends on `^0.2.0`.
+
+What we use:
+- `start({ resumeSession })` — public option, calls ACP `loadSession` internally
+- `prompt(text)` + `stop()` — v0.1.0 unchanged
+
+What we DON'T need from claude-code-agent v0.2:
+- Public `loadSession` method (codex F9 clarified — internal only)
+- Replay protection idempotency keys (shim replay is informational, no tool re-execution observed)
+- `fork()` (still v1.1)
+
+---
+
+## 10. Risks & posture
+
+### R1 — Matrix protocol complexity
+E2EE adds a fully separate code path. **v0.1 ships with E2EE disabled** — encrypted rooms refused at gateway with explicit error. Multi-participant rooms also refused (v0.1 is DM-only).
+
+### R2 — ~~Per-channel memory pressure~~ — **DISSOLVED**
+Ephemeral spawn-per-message means baseline daemon RAM is ~50MB; each turn briefly spikes ~200MB during claude binary's lifetime, then back to baseline. No N-concurrent-claude-processes problem.
+
+### R3 — Single-user assumption
+v0.1 is single-user: `daemon.adminUserIds` lists Coral's transport-prefixed IDs (e.g. `matrix:@coral:matrix.org`). Non-admin senders in a bound DM get rejected with audit log entry. Multi-user with roles → v0.1.x.
+
+### R4 — Skill conflicts across profiles
+Non-risk (isolated profile dirs).
+
+### R5 — ~~LLM backend over-design~~ — **dissolved**
+D2: no LLMBackend abstraction. Multi-vendor via `ANTHROPIC_BASE_URL` proxy at deployment, not at code level.
+
+### Cold-start UX (D1=A)
+Ephemeral mode: 5-10s per message before first token. Gateway sends Matrix `m.typing` indicator during. Coral's IM rate (~human-paced) makes this acceptable. If dogfooding reveals pain, v0.2 may add a warm hot-pool (NOT residency — pool-of-1).
+
+### M0 prototype gate is the hinge
+Concurrent claude binaries on a single OAuth subscription must work. If M0 reveals auth collision or rate-limit pathology, plan rev 5 is invalidated; rev 6 designs a queue-based serialization model. **No daemon code lands before M0 passes.**
+
+---
+
+## 11. Open decisions
+
+| # | Question | Status |
+|---|----------|--------|
+| Q1 | LLM backend abstraction timing | **Resolved (D2)**: never. Multi-vendor via `ANTHROPIC_BASE_URL` proxy. |
+| Q2 | Streaming UX (Matrix m.replace vs final-only) | **Resolved**: final-only in v0.1 on both transports. Streaming → v0.1.x. |
+| Q3 | resumeSession hard block vs stateless v0.1 | **Resolved (D10)**: hard block; claude-code-agent v0.2 shipped 2026-05-14. |
+| Q4 | Project name (does "nps" stand for something?) | **Open. Owner: Coral. Deadline: before npm publish.** Fallback codename: `nps-cli`. |
+
+---
+
+## 12. Comparison with sps-cli (so we don't accidentally rebuild it)
+
+| Dimension | sps-cli | nps-cli |
+|---|---|---|
+| Form factor | Pipeline orchestrator | Conversational daemon |
+| Concurrency | Single worker, serial (v0.37.2 deliberate) | Ephemeral process per message; no parallelism within a channel |
+| Trigger | File changes in `~/.coral/projects/...` | IM messages |
+| Output | Card state machine + worker artifacts | Reply messages in IM channel |
+| Skill scope | sps global + project | nps profile-local (cwd = workspace, with system prompt + skills resolved by M-WS) |
+| Web UI | Yes (console) | Deferred to v0.1.x |
+| Platform | Cross-platform | Linux-only (v0.1) |
+| Persistence | Card state in files | Per-channel SessionStore + audit log |
+
+Two different products with one shared runtime (`@coralai/claude-code-agent`). The Phase 1 extraction is what makes both possible.
+
+---
+
+## 13. Distribution
+
+```json
+{
+  "name": "@coralai/nps-cli",
+  "version": "0.1.0",
+  "type": "module",
+  "bin": { "nps": "dist/main.js" },
+  "files": ["dist", "systemd/", "README.md"],
+  "engines": { "node": ">=18" },
+  "os": ["linux"]
+}
+```
+
+CI/CD (GitHub Actions, to be added in M7):
+- `on: push to main` → `npm test && tsc --noEmit`
+- `on: tag v*.*.*` → `npm publish`
+- CI smoke: `npm install -g <local pack>` + `nps --version`
+
+systemd `ExecStart` pattern (documented by `nps daemon install-service`):
+```
+ExecStart=/usr/bin/env node /home/<user>/.npm-global/bin/nps daemon start --foreground
+```
+
+---
+
+## 14. NOT in scope (v0.1, rev 5 final)
+
+- nps-cli's own `LLMBackend` abstraction (D2)
+- Plugin extension model for nps-cli (D3)
+- sps-cli chat-worker integration
+- Pure library release without daemon
+- Per-channel residency / process cache (codex F2)
+- Multi-participant Matrix rooms (codex F8)
+- Telegram gateway (codex F6 — hidden work; own milestone in v0.1.x)
+- IM-driven binding commands `/bind /unbind /persona /reset` (codex F5)
+- Web admin console (codex F7)
+- Cross-agent context handoff (D8)
+- Voice messages STT/TTS (D9)
+- Cost tracking (D6)
+- Streaming UX (Matrix m.replace) (Q2)
+- macOS launchd / Windows (codex F20 — Linux-only)
+- Public `loadSession` method in claude-code-agent (codex F9 — internal only)
+
+---
+
+## 15. Implementation status
+
+| Component | Status |
+|-----------|--------|
+| `@coralai/claude-code-agent` v0.2 (resumeSession) | ✅ Shipped 2026-05-14 |
+| Skeleton `jarvis-skills/nps-cli/` | ✅ Landed 2026-05-14 |
+| **M0 lifecycle prototype gate** | ✅ **PASSED 2026-05-14** (solo=4847ms, parallel=4712ms, ratio 0.97x; all 6 criteria green) |
+| **M0a resume prototype gate** | ✅ **PASSED 2026-05-14** (stored "42" → resumed → recalled "42"; bogus sessionId → SESSION_LOST; 5/5 criteria) |
+| **M-WS workspace prototype gate** | ✅ **PASSED 2026-05-14** (profile-as-cwd loads CLAUDE.md + skills; workspace via absolute path also works without `additionalDirectories`) |
+| **M5a Matrix transport spike** | ✅ **PASSED 2026-05-14** (im.wymsn.com sync 218ms, DM classification works, test send succeeded; lib decision: `matrix-js-sdk@41 direct`) |
+| **M1-M13 implementation** | ✅ **DONE 2026-05-14** (62/62 unit tests; agent invoke smoke green; daemon RPC works) |
+| **Real-world Matrix DM E2E** | ✅ **PASSED 2026-05-15** (dedicated `@nps-bot:wymsn.com` account registered via /register API; DM rooms with both @elon and @yuguo; T1 /help / T2 prompt / T3 /status all replied correctly; sessions persisted with compatHash) |
+| **systemd deployment** | ✅ **ACTIVE** (`nps daemon install-service` writes wrapper at `~/.nps/run-daemon.sh` + unit at `~/.config/systemd/user/nps.service`; wrapper sources `~/.coral/env` to handle `export KEY=value` lines + inherits PATH so claude + claude-agent-acp resolve; `systemctl --user enable --now nps` works; `loginctl enable-linger` set) |
+| Project name (Q4) | ✅ **Locked: nps-cli** (D2=A 2026-05-15); package `private` flag removed; LICENSE + publishConfig + repository added |
+| npm publish | ⏳ Pending dogfood validation (D3=B, target 0.1.0 stable after a few days of use) |
+
+---
+
+*Vision rev 5 · 2026-05-14 · aligned with CEO plan rev 5 + eng plan rev 5*

package/dist/audit-log.d.ts

@@ -0,0 +1,26 @@
+import type { Logger } from 'pino';
+export interface AuditEntry {
+    ts: string;
+    sender: string;
+    transport: 'matrix' | 'telegram' | 'cli';
+    channel?: string;
+    command_or_event: string;
+    decision: 'accepted' | 'denied' | 'dropped' | 'error';
+    profile?: string;
+    detail?: string;
+}
+export declare class AuditLog {
+    private readonly path;
+    private logger;
+    private fd;
+    private bytesWritten;
+    constructor(path: string, logger?: Logger);
+    private open;
+    append(entry: Omit<AuditEntry, 'ts'> & {
+        ts?: string;
+    }): void;
+    /** Atomic rotation: close current → shift .3→.4, .2→.3 ... → rename current to .0 → reopen */
+    private rotate;
+    close(): void;
+}
+//# sourceMappingURL=audit-log.d.ts.map

package/dist/audit-log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-log.d.ts","sourceRoot":"","sources":["../src/audit-log.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAMnC,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,QAAQ,GAAG,UAAU,GAAG,KAAK,CAAC;IACzC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,MAAM,CAAC;IACzB,QAAQ,EAAE,UAAU,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC;IACtD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,QAAQ;IAKjB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAJvB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,EAAE,CAAqB;IAC/B,OAAO,CAAC,YAAY,CAAK;gBAEN,IAAI,EAAE,MAAM,EAC7B,MAAM,CAAC,EAAE,MAAM;IAMjB,OAAO,CAAC,IAAI;IAmBZ,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,GAAG;QAAE,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAsB7D,8FAA8F;IAC9F,OAAO,CAAC,MAAM;IA6Bd,KAAK,IAAI,IAAI;CAMd"}

package/dist/audit-log.js

@@ -0,0 +1,120 @@
+/**
+ * M12 — audit log.
+ *
+ * jsonl append at `~/.nps/audit.jsonl`, mode 0600. Each entry is `{ v: 1, ts, ... }`
+ * for forward compatibility. Rotation at 50MB → `.0`; existing `.0..3` shift up;
+ * `.4` deleted. On ENOSPC: log to pino as [CRITICAL], do NOT block daemon.
+ */
+import { existsSync, mkdirSync, openSync, fstatSync, writeSync, closeSync, renameSync, unlinkSync, chmodSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { getLogger } from './logger.js';
+const ROTATE_BYTES = 50 * 1024 * 1024; // 50 MB
+const RETAIN = 5; // .0..4
+export class AuditLog {
+    path;
+    logger;
+    fd;
+    bytesWritten = 0;
+    constructor(path, logger) {
+        this.path = path;
+        this.logger = logger ?? getLogger('audit');
+        this.open();
+    }
+    open() {
+        try {
+            mkdirSync(dirname(this.path), { recursive: true });
+            // O_APPEND is implicit by writing at end; openSync('a') opens append-only.
+            this.fd = openSync(this.path, 'a', 0o600);
+            // Ensure perms even if file pre-existed with looser mode.
+            try {
+                chmodSync(this.path, 0o600);
+            }
+            catch { /* best-effort */ }
+            // Estimate current size for rotation budget
+            try {
+                this.bytesWritten = fstatSync(this.fd).size;
+            }
+            catch {
+                this.bytesWritten = 0;
+            }
+        }
+        catch (e) {
+            this.logger.error({ err: e instanceof Error ? e.message : e }, '[CRITICAL] audit log open failed');
+            this.fd = undefined;
+        }
+    }
+    append(entry) {
+        if (this.fd === undefined) {
+            // Failed open — skip silently per plan (audit must never block daemon).
+            return;
+        }
+        const line = JSON.stringify({ v: 1, ts: entry.ts ?? new Date().toISOString(), ...entry }) + '\n';
+        try {
+            writeSync(this.fd, line);
+            this.bytesWritten += Buffer.byteLength(line, 'utf8');
+            if (this.bytesWritten >= ROTATE_BYTES) {
+                this.rotate();
+            }
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            if (msg.includes('ENOSPC') || msg.includes('no space')) {
+                this.logger.error('[CRITICAL] audit log unavailable: disk full');
+            }
+            else {
+                this.logger.error({ err: msg }, '[CRITICAL] audit log write failed');
+            }
+        }
+    }
+    /** Atomic rotation: close current → shift .3→.4, .2→.3 ... → rename current to .0 → reopen */
+    rotate() {
+        if (this.fd === undefined)
+            return;
+        try {
+            closeSync(this.fd);
+            this.fd = undefined;
+            // Delete oldest if exists
+            const oldest = `${this.path}.${RETAIN - 1}`;
+            if (existsSync(oldest)) {
+                try {
+                    unlinkSync(oldest);
+                }
+                catch { /* ignore */ }
+            }
+            // Shift remaining
+            for (let i = RETAIN - 2; i >= 0; i--) {
+                const src = `${this.path}.${i}`;
+                const dst = `${this.path}.${i + 1}`;
+                if (existsSync(src)) {
+                    try {
+                        renameSync(src, dst);
+                    }
+                    catch { /* ignore */ }
+                }
+            }
+            // Move current → .0
+            if (existsSync(this.path)) {
+                try {
+                    renameSync(this.path, `${this.path}.0`);
+                }
+                catch { /* ignore */ }
+            }
+        }
+        catch (e) {
+            this.logger.error({ err: e instanceof Error ? e.message : e }, '[CRITICAL] audit rotation failed');
+        }
+        finally {
+            this.open();
+        }
+    }
+    close() {
+        if (this.fd !== undefined) {
+            try {
+                closeSync(this.fd);
+            }
+            catch { /* ignore */ }
+            this.fd = undefined;
+        }
+    }
+}
+//# sourceMappingURL=audit-log.js.map

package/dist/audit-log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-log.js","sourceRoot":"","sources":["../src/audit-log.ts"],"names":[],"mappings":"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"}

package/dist/bindings/bindings-loader.d.ts

@@ -0,0 +1,19 @@
+import { EventEmitter } from 'node:events';
+import type { Logger } from 'pino';
+import type { BindingsFile } from '../config/schema.js';
+export type Transport = 'matrix' | 'telegram';
+export declare class BindingsLoader extends EventEmitter {
+    private readonly path;
+    private logger;
+    private bindings;
+    private watcher;
+    constructor(path: string, logger?: Logger);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private reload;
+    /** Look up profile name for a Matrix channel id; undefined if unbound. */
+    lookupMatrix(channelId: string): string | undefined;
+    /** Snapshot of current bindings (read-only). */
+    snapshot(): BindingsFile;
+}
+//# sourceMappingURL=bindings-loader.d.ts.map

package/dist/bindings/bindings-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bindings-loader.d.ts","sourceRoot":"","sources":["../../src/bindings/bindings-loader.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAGnC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,UAAU,CAAC;AAE9C,qBAAa,cAAe,SAAQ,YAAY;IAM5C,OAAO,CAAC,QAAQ,CAAC,IAAI;IALvB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAgC;IAChD,OAAO,CAAC,OAAO,CAAwB;gBAGpB,IAAI,EAAE,MAAM,EAC7B,MAAM,CAAC,EAAE,MAAM;IAMX,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAiBtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAO3B,OAAO,CAAC,MAAM;IA4Bd,0EAA0E;IAC1E,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAInD,gDAAgD;IAChD,QAAQ,IAAI,YAAY;CAGzB"}