# Migrating damocles onto hyperhive

The plan calls out damocles → hyperhive as a future migration. This doc lays
out the options + recommended path. Not yet executed.

## Current state (separate from hyperhive)

`damocles` is a declarative nixos-container on `muede-lpt2`:

- Declared in `nixosConfigurations/muede-lpt2/containers.nix`
- Built from `nixosConfigurations/damocles/` (claude-container.nix + extras)
- Bind-mounts (RO unless noted):
  - `/etc/nix/distributed-build-key`
  - `/persist/damocles-ssh`
  - `/persist/damocles-lab` (RW — persistent work dir)
- `privateNetwork = false`
- Has its own systemd-services override (`TimeoutStopSec = 60s`, `RestartSec = 5s`)
- Hosts the user's primary day-job Claude Code session, not part of the swarm

## Options

### A. Sub-agent under hive-c0re
Make damocles a `hive-agent-damocles` (or whatever short name fits the 9-char cap).
hive-c0re owns its lifecycle; its config flake is the manager-editable
`/var/lib/hyperhive/agents/damocles/config/`.

Pros: uniform — message broker, dashboard, approval flow apply to damocles too.
Cons: a lot of damocles-specific state (bind-mounts, ssh keys, build keys) has to
be modeled as per-agent config. Today's `agent.nix` schema doesn't support
declaring bind-mounts; would need to extend. And the user's day-job session
becoming subject to hive-c0re lifecycle (restarts on rebuild) is invasive.

### B. Peer container (broker-integrated, lifecycle-independent)
Keep damocles declarative; have its harness install `hive-ag3nt` and connect to
the broker via a bind-mounted socket. damocles can send/recv messages with
other sub-agents but is not managed by hive-c0re.

Pros: low blast radius. damocles keeps its bind-mounts + its own restart policy.
Manager can route messages to it (it's just another inbox key on the broker).
Cons: two lifecycle mechanisms coexist forever; "damocles" doesn't appear in the
dashboard's container list (it filters `hive-` and `hm1nd`).

### C. Don't migrate
damocles stays out of hyperhive. The two systems coexist; the user's day-job
Claude and the swarm are deliberately separate.

Pros: zero work; aligns with the actual usage pattern (day-job vs. experiment).
Cons: no message routing between damocles and the swarm.

## Recommended

**C for now, B once cross-pollination is wanted.** Hyperhive's invariants
(11-char container names, manager-driven lifecycle, sealed `applied/` config)
fit poorly with damocles's role as the user's working Claude. Wait until there's
a concrete reason to wire them together (e.g. "I want to ask hm1nd from inside
damocles") and then do B — extend the broker socket bind into damocles and
install `hive-ag3nt` there. No need to subsume damocles under hive-c0re.

If/when option B is taken:

1. Add `${hyperhive.packages.${system}.default}/bin/hive-ag3nt` (or just
   `pkgs.hyperhive`) to `nixosConfigurations/damocles/claude-container.nix`.
2. Bind-mount `/run/hyperhive/agents/damocles/` into damocles at `/run/hive/`.
   On the host, this is just another dir hive-c0re needs to know about —
   maybe expose a "peer agents" registration mechanism in the broker.
3. Run `hive-ag3nt serve` as a systemd unit inside damocles (separate from
   the user's interactive claude session — broker peer, not turn-loop).
4. Optionally: add a `hive-c0re register-peer damocles` admin verb so the
   container appears in `list()` and the dashboard. (Or just hard-list it.)

A is on the table only if the user's workflow shifts toward "the swarm IS the
day-job environment" — at which point damocles dissolves into a `hive-agent-*`
naturally.