devagent OS-user boundary — tier-1 host provisioning + rollback (pop-mini pilot)

[thompsonson]

Summary

The tier-1 half of the devagent OS-user boundary: the privileged, once-only,
host-specific steps a human runs and can roll back. Current pilot host: computer
(was pop-mini; flipped by the operator). The mechanism is host-agnostic — any
modern systemd host where gpg-agent is socket-activated. Repeat per host.

This issue does not restate the design — the merged doc set is the authority:

• Model, vocabulary, and the V1–V7 decisions: dev docs/design/devagent-boundary.md
  • docs/design/devagent-security-boundary.md (merged, dev#186).
• Tier-2 — idempotent mechanicals (socketdir loan link + its user unit, the
  agents.slice user unit, /srv/dev-shared checkout + ACLs, broker-contract
  verification): owned by dev provision devagent --apply. dev provision devagent --dry-run is the single source of truth for those commands and emits the
  tier-1 commands below — treat any divergence between it and this issue as a bug
  in one of them.
• Tier-3 — continuous health: dev doctor --devagent.
• App-code contract ([project.x] user =, uid-aware tmux dispatch, the broker
  op-set): dev#154.

Prerequisites

• A dedicated sign-only ([S]-only) OpenPGP signing subkey on mt's key,
  appointed as the loaned keygrip. A restricted extra-socket permits PKSIGN and
  PKDECRYPT — pinning the loan to an [S]-only subkey is what excludes decryption
  (V6). Default keys have no such subkey; create one (gpg --edit-key <fpr> →
  addkey → sign-only) or via dev#162 dev key create. Record its fingerprint and
  keygrip: gpg --list-keys --with-subkey-fingerprints --with-keygrip.
• mt's gpg-agent kept unlocked by the existing weekly preset flow
  (allow-preset-passphrase + gpg-preset-passphrase <sign-subkey-keygrip>).
• Both mt and devagent get enable-linger. /run/gnupg/shared is tmpfs
  and the extra-socket only exists while mt's gpg-agent is running; without mt
  lingering, a reboot breaks devagent signing until mt next logs in.

Tier-1 steps

1. devagent user + shared group

getent group devgroup   || sudo groupadd devgroup
id -u devagent >/dev/null 2>&1 || \
  sudo useradd -m -s /usr/sbin/nologin -G devgroup devagent   # no interactive shell — v1 is loan-only, the broker builds env from scratch
sudo usermod -aG devgroup mt
sudo loginctl enable-linger devagent
sudo loginctl enable-linger mt          # keeps the lender (mt's gpg-agent) alive across reboots

Verify: id devagent shows devgroup; loginctl show-user devagent and
loginctl show-user mt both show Linger=yes.

2. Relocate + group-grant the restricted extra-socket

The pilot host runs gpg-agent --supervised (systemd socket-activated) —
verified on both computer (gpg 2.4.8) and pop-mini (gpg 2.2.27). Two things
follow:

• extra-socket in gpg-agent.conf is ignored in supervised mode — gpg-agent
  gets pre-bound fds from systemd and never creates its own sockets. Do not add it.
• /run/user/<uid> is 0700 mt:mt, logind-owned, mode hardcoded — a socket
  anywhere under it is connect()-unreachable cross-uid regardless of its own mode.
  The extra socket must move out of /run/user/<uid>, and on a socket-activated
  host that is done in the .socket unit, not gpg-agent.conf.

Keep in ~mt/.gnupg/gpg-agent.conf only:

allow-preset-passphrase
max-cache-ttl 604800

Stated decision, not a side effect: max-cache-ttl 604800 is per-agent, not
per-key — it relaxes cache lifetime for all of mt's keys for a week. Accepted on
a single-operator host; recorded here so the choice is deliberate.

Shared directory (tmpfs — recreated each boot), setgid so anything created in
it lands devgroup — /etc/tmpfiles.d/gnupg-shared.conf:

d /run/gnupg/shared 2750 mt devgroup -

User drop-in on gpg-agent-extra.socket — relocates the socket and sets mode
natively. SocketGroup=devgroup is belt-and-braces: the socket already inherits
devgroup from the setgid 2750 dir on creation, so SocketGroup= may log a
benign "Failed to set socket group" if mt's systemd --user session predates the
usermod -aG devgroup mt above (a non-root manager can't chgrp to a group it
isn't in) — the setgid dir covers it either way. The empty ListenStream= resets
the vendor value before the new one:

# ~mt/.config/systemd/user/gpg-agent-extra.socket.d/shared.conf
[Socket]
ListenStream=
ListenStream=/run/gnupg/shared/S.gpg-agent.extra
SocketMode=0660
SocketGroup=devgroup

sudo systemd-tmpfiles --create /etc/tmpfiles.d/gnupg-shared.conf
systemctl --user daemon-reload
gpgconf --kill gpg-agent                        # KILL FIRST — see note
systemctl --user restart gpg-agent-extra.socket
gpg -K >/dev/null 2>&1 && echo "mt gpg ok"      # sanity: agent re-activates on this call

Order matters. systemd refuses restart gpg-agent-extra.socket while its
Accept=no acceptor gpg-agent.service is active ("Socket service … already
active, refusing") — so a restart-then-kill order fails at the restart. Kill the
agent first; the .socket restart then binds the relocated /run/gnupg/shared
path, and gpg-agent re-activates on the next connection. (Killing also avoids the
separate stale-fd trap: a running agent keeps the old, now-unlinked socket fd and
never serves the relocated path — a "V2 blocked" false negative.)

If usermod -aG devgroup mt was run in this same session, log out/in (or
sudo loginctl terminate-user mt) before this step so SocketGroup= applies
cleanly — otherwise rely on the setgid dir and ignore the journal warning.

Autonomous (--daemon) hosts — non-systemd, or gpg-agent not socket-activated:
there, use extra-socket /run/gnupg/shared/S.gpg-agent.extra in gpg-agent.conf
plus an ExecStartPost=/bin/sh -c 'chgrp devgroup … && chmod 0660 …' on the
agent service. Any modern Ubuntu/Pop host is socket-activated — use the drop-in
above.

3. V2 go/no-go pre-test — before the sudoers line

Prove a different uid can actually connect() to the extra-socket. Nothing
downstream is worth wiring until this passes.

DEVAGENT_UID=$(id -u devagent)
# sudo resets the env; gpgconf needs XDG_RUNTIME_DIR to place the 0700 socketdir
sudo -u devagent env XDG_RUNTIME_DIR="/run/user/$DEVAGENT_UID" gpgconf --create-socketdir
sudo -u devagent ln -sfn /run/gnupg/shared/S.gpg-agent.extra \
     "/run/user/$DEVAGENT_UID/gnupg/S.gpg-agent"
gpg --export <PRIMARY_FPR> | sudo -u devagent gpg --homedir /home/devagent/.gnupg --import
echo test | sudo -u devagent env XDG_RUNTIME_DIR="/run/user/$DEVAGENT_UID" \
     gpg --homedir /home/devagent/.gnupg -u '<SIGN_SUBKEY_FPR>!' --sign > /dev/null && echo "V2 OK"

If connect() is refused: confirm ls -l /run/gnupg/shared/S.gpg-agent.extra
shows srw-rw---- mt devgroup and the dir is 2750 mt devgroup — a wrong group or
a socket still under /run/user/<uid> is the usual cause. If the drop-in took and
it still fails, socket forwarding (socat / ssh -R) is the last resort; if that
also fails the design flips to SSH signing or a per-uid key (dev#162) — stop and
escalate, do not proceed to step 5.

The socketdir symlink created here is on tmpfs and vanishes on reboot — its
permanent home is a devagent user unit created in tier-2 by dev provision.
This step only proves the mechanism.

4. Tighten mt's home

chmod 700 /home/mt

Reversible (chmod 755), so safe to apply and observe — but check first:

• sysbak / rsnapshot: runs as root (ignores 700) or drops privileges? If it
  drops privs it loses read access to ~mt.
• Nothing reads ~mt/.local/share/chezmoi from another identity — the pilot
  clones dotfiles fresh, it does not read mt's working copy.
• Editor / LSP remote-helpers that stat ~mt.
• systemd system units with ProtectHome= interactions.
• Confirm nothing devagent needs lives under ~mt (the extra-socket is at
  /run/gnupg/shared, not ~mt).

5. Sudoers — the trust root

sudo visudo -cf /dev/stdin <<'EOF'
mt ALL=(devagent) NOPASSWD: /usr/lib/dev/agent-launch
EOF
# then install as /etc/sudoers.d/dev-agent-launch, mode 0440

Absolute path, no ARGV constraint — by design. Security rests on the broker
(agent-launch) enumerating its ops and self-validating its own argv, not on
sudoers argument matching (dev#154). Install only after step 3 passed and the
broker binary is in place (tier-2 verifies its op-set against the dev#154
contract).

Verification checklist (tier-1)

• id devagent → devgroup; loginctl show-user devagent and ... mt → Linger=yes
• ~mt/.gnupg/gpg-agent.conf has allow-preset-passphrase + max-cache-ttl 604800 and no extra-socket line
• /run/gnupg/shared is a dir, mode 2750, owner mt:devgroup
• ls -l /run/gnupg/shared/S.gpg-agent.extra → srw-rw---- mt devgroup, i.e. a socket at that path (not under /run/user/), mode 0660, group devgroup, after systemctl --user restart gpg-agent-extra.socket
• V2 pre-test passes — sudo -u devagent … --sign succeeds while mt's agent has the sign-only subkey preset
• sudo -u devagent gpg --homedir /home/devagent/.gnupg --list-secret-keys → empty
• loaned keygrip is a sign-only subkey — gpg --list-keys --with-colons --with-keygrip: the sub: whose following grp: matches shows capability s only (not se / e)
• ls -ld /home/mt → drwx------
• sudo visudo -cf /etc/sudoers.d/dev-agent-launch → OK; sudo -n -u devagent /usr/lib/dev/agent-launch runs with no password prompt

Rollback

sudo userdel -r devagent
sudo gpasswd -d mt devgroup && sudo groupdel devgroup
sudo rm -f /etc/sudoers.d/dev-agent-launch /etc/tmpfiles.d/gnupg-shared.conf
rm -rf ~mt/.config/systemd/user/gpg-agent-extra.socket.d
systemctl --user daemon-reload && systemctl --user restart gpg-agent-extra.socket   # restores the vendor path /run/user/<uid>/gnupg/S.gpg-agent.extra
sudo rm -rf /run/gnupg/shared
# edit ~mt/.gnupg/gpg-agent.conf — remove allow-preset-passphrase / max-cache-ttl, then:
gpg-connect-agent reloadagent /bye
chmod 755 /home/mt          # or the pre-change mode
sudo loginctl disable-linger devagent
# tier-2 artefacts (agents.slice + socketdir user units, /srv/dev-shared ACLs): dev provision devagent revert path (dev#154)

The dedicated sign-only subkey can stay on mt's key — it is harmless unused. Remove
with gpg --edit-key <fpr> → key N → delkey if desired.

Non-goals

• No key generation here — the sign-only subkey is a prerequisite (dev#162
  dev key create).
• One shared devagent; no per-project users in v1.
• No cross-host automation — one pilot host at a time (currently computer),
  repeat per host once proven.
• No run_once_* chezmoi script for these sensitive steps on the first pass —
  done by hand and reviewed; scripted only once proven safe.

Companions

• dev docs/design/devagent-boundary.md + devagent-security-boundary.md —
  model, vocabulary, V1–V7 (merged in dev#186).
• dev#154 — app-code scope: user = field, uid-aware tmux dispatch, broker op-set
  contract, attach-via-proxy.
• dev#162 — dev key create (the sign-only subkey).
• dev#159 — per-role git signing identity (GIT_CONFIG_GLOBAL); devagent's git
  config is deferred to it.
• dev#129 — structured agent API; shrinks the attach/scrape surface once it lands.
• dev#151 — direct-launch process leak (reap).

---

https://claude.ai/code/session_01WDcE2CAYzzJTMY6ubRmt94

[thompsonson]

Advisory review (audit, 2026-09-05)

Runbook corrections before provisioning pop-mini. Current state: devagent does not exist there; pop-mini sudo requires a password, so keep the sensitive steps human-assisted (matches the manual-first intent).

• Step 2 (gpg loan): the loan symlink must go in devagent's socketdir ($XDG_RUNTIME_DIR/gnupg/S.gpg-agent, i.e. /run/user/<devagent-uid>/gnupg/), not ~devagent/.gnupg/S.gpg-agent — gpg resolves the agent via socketdir (verified on gpg 2.2.27 and 2.4.8). Also verify the socket is connectable by devagent after creation (sockets are created 0700 owner-only; gpg-agent has no perms option). Pre-test on the pilot; if connect fails, fall back to a chmod g+rw nudge, or socket forwarding (ssh -R/socat), or a 0770 socket in a 0750 devgroup dir — pick before wiring the sudoers.
• Step 7 (agents.slice): use /etc/systemd/user/agents.slice (a system-wide user unit) so devagent's user manager applies it to systemd-run --user --slice=agents.slice; then systemctl --user daemon-reload in devagent's manager. /etc/systemd/system/agents.slice is not in the user-manager load path.
• Step 5 (helper install): install the helper from the same dev release that ships the user= routing, and version-lock it here, to avoid cross-repo drift; sanity-check dev-agent-helper op set matches dev#154's contract before installing the sudoers line.
• Step 8 (devagent creds): git-signing placeholder is correct; note it only works while mt's agent has the key preset (weekly unlock) — record the operational dependency so it's not a silent failure.
• V4 note: a single shared worktree (mt + devagent both mutating) risks concurrent-git (git index.lock) collisions — acceptable for a single-agent pilot; document the "one actor at a time" constraint or split per-uid checkouts later.
• V5 note: after step 3 (chmod 700 /home/mt), re-test anything that reads through ~mt from another identity (e.g. sysbak).

Full audit commentary also posted on thompsonson/dev#154.

[thompsonson]

Advisor response (2026-09-05)

Verified against pop-mini (gpg 2.2.27; devagent absent; mt already has Linger=yes).

On the three corrections — full mechanism notes on dev#154. Short version: V1 (socketdir, not ~/.gnupg) confirmed, and the loan link must be re-established per boot (tmpfs) via a devagent user unit, not run_once; V2 (cross-uid socket perms) is a go/no-go gate — every socket here is 0600 owner-only, prove connect() works before the sudoers line; V3 (slice is a user unit) confirmed, and for a single-agent pilot ~devagent/.config/systemd/user/agents.slice is cleaner than a system-wide user unit.

Runbook shape. Keep #78 as the tier-1 record — the privileged, once-only, host-specific steps a human runs and can roll back: user/group/linger, the sudoers line, chmod 700 ~mt, the gpg-agent.conf edit. Let dev provision devagent own the idempotent mechanicals (see dev#154). #78 stops being a copy-paste script for the privileged parts and becomes "here are the human steps, why each one, and how to undo them" — which matches the manual-first non-goal already in it.

V4 / shared worktree — confirm, and I'd enforce, not just document. index.lock is the visible symptom; worse are (a) one identity's checkout/rebase moving the tree under the other's uncommitted edits, (b) files written devagent:devgroup that mt's tooling then re-chmods in a loop, (c) shared .git/hooks — a hook devagent can write is a hook mt runs. For the pilot, use a separate checkout under /srv/dev-shared/<project> that mt never touches, rather than sharing mt's working copy — that removes the class of problem instead of documenting around it. Per-uid checkouts "later" should be "now" past the first smoke test.

V5 / ~mt 700 — confirm, expand the pre-flip checklist. It's reversible (chmod 755), so low-risk to try and observe, but enumerate first: sysbak/rsnapshot (does it drop privs, or run as root? root ignores 700), anything reading /home/mt/.local/share/chezmoi (the pilot must clone dotfiles fresh, not read mt's working copy), editor/LSP remotes, Tailscale or systemd system units with ProtectHome. Nothing devagent needs should sit under ~mt once extra-socket moves to /run/gnupg/shared — verify that.

Two things not yet in the thread:

• /run/gnupg/shared is tmpfs. The systemd-tmpfiles rule recreates the dir on boot, but the extra-socket inside it only appears when mt's gpg-agent starts. mt has Linger=yes here so it auto-starts unattended — make that an explicit prerequisite (both mt and devagent linger), or a reboot leaves devagent unable to sign until mt logs in.
• max-cache-ttl 604800 blast radius. That's per-agent, not per-key — it relaxes cache lifetime for all of mt's keys for a week, not just the loaned one. Probably fine on a single-operator host, but state it so it's a decision, not a side effect.

Work not started on pop-mini — good; these all land before provisioning.

---

https://claude.ai/code/session_01WDcE2CAYzzJTMY6ubRmt94

[thompsonson]

Superseded body (original, 2026-09-05) — kept for history

The issue body was rewritten on 2026-09-06 to (a) narrow scope to tier-1 only — the merged design (dev#186) assigns the idempotent mechanicals to dev provision devagent, and duplicating them here guarantees drift — and (b) fold in the frozen V1–V7 corrections from the advisory rounds (socketdir loan link, V2 socket-mode gate, sign-only subkey pin, user-unit slice, both-sides linger, expanded ~mt 700 checklist). Original 8-step version below.

Original body

Summary

Machine-provisioning runbook for the devagent OS-user boundary. This is the sysadmin half split out of thompsonson/dev#154 — everything here is done by a human (or a reviewed, deliberately-manual chezmoi script) on a specific host, never by dev application code. dev#154 is narrowed to just: the [project.foo] user = "devagent" config field, uid-aware tmux dispatch, and the launch-helper's contract (what commands it accepts). This issue is that helper's deployment plus everything around it.

Pilot host: pop-mini. Repeat on computer only after this is proven.

Non-goals (carried from dev#158/#154, unchanged here)

• No key generation (separate: dev#162 dev key create).
• No per-project users yet — one shared devagent first.
• No cross-host automation in v1 — each host provisioned once, by hand, reviewed.
• No automated run_once_* chezmoi script for the sensitive steps (user creation, sudoers, home permissions) on the first pass — do it manually and verified; consider scripting once proven safe.

Sequence

1. Shared group + devagent user

sudo groupadd devgroup                       # shared group for mt + devagent
sudo useradd -m -s /usr/bin/zsh -G devgroup devagent
sudo usermod -aG devgroup mt
sudo loginctl enable-linger devagent          # devagent's user manager persists without a login session

Verify: id devagent shows devgroup; loginctl show-user devagent | grep Linger → yes.

2. GPG extra-socket at a neutral path (loan mechanism)

~mt/.gnupg/gpg-agent.conf add:

extra-socket /run/gnupg/shared/S.gpg-agent.extra
allow-preset-passphrase
max-cache-ttl 604800

(the last two are the existing weekly gpg-unlock flow — see prior session notes)

/etc/tmpfiles.d/gnupg-shared.conf:

d /run/gnupg/shared 0750 mt devgroup -

Apply + reload:

sudo systemd-tmpfiles --create /etc/tmpfiles.d/gnupg-shared.conf
gpg-connect-agent reloadagent /bye

devagent side — public key only, symlink to the loaned socket:

gpg --export 37A8C885224A52071F86E4CDE5BE71AE470FEEF7 | sudo -u devagent gpg --homedir /home/devagent/.gnupg --import
sudo -u devagent ln -sf /run/gnupg/shared/S.gpg-agent.extra /home/devagent/.gnupg/S.gpg-agent

Verify (proves the loan without devagent ever touching the private key):

sudo -u devagent gpg --homedir /home/devagent/.gnupg --list-secret-keys   # empty — no private key
echo test | sudo -u devagent gpg -u 37A8C885224A52071F86E4CDE5BE71AE470FEEF7 --clearsign   # succeeds iff mt's agent has the key preset (gpg-unlock)

3. Tighten mt's home

chmod 700 /home/mt

Test afterward that nothing mt relies on expected group/other read on the home dir (some services/backup tooling assume it — check sysbak config paths aren't reading through ~mt from another identity).

4. Shared-group project directory (pilot: one low-stakes project)

sudo mkdir -p /srv/dev-shared/<project>
sudo chown mt:devgroup /srv/dev-shared/<project>
sudo chmod 2770 /srv/dev-shared/<project>                       # setgid: new files inherit devgroup
sudo setfacl -d -m g:devgroup:rwx -m u:mt:rwx -m u:devagent:rwx /srv/dev-shared/<project>
git clone <repo-url> /srv/dev-shared/<project>

5. Launch-helper binary (built in dev repo, installed here)

Contract defined in dev#154 (enumerated ops: launch <project-key>, tmux <fixed-op-set>, reap <pid-in-slice> — no free-form paths/commands, helper validates everything itself). Deployment only:

sudo install -o root -g root -m 0755 <dev-repo>/target/release/dev-agent-helper /usr/lib/dev/agent-launch

6. Sudoers — narrow, fixed-shape

sudo visudo -cf - <<'EOF'   # validate before installing
mt ALL=(devagent) NOPASSWD: /usr/lib/dev/agent-launch
EOF
# then install to /etc/sudoers.d/dev-agent-launch, mode 0440

No wildcards on mt's side — the helper itself enumerates and validates its own argv (per dev#154's design).

7. QoS slice for the agent fleet

/etc/systemd/system/agents.slice:

[Unit]
Description=Agent fleet resource slice
[Slice]
MemoryHigh=8G
CPUWeight=50

sudo systemctl daemon-reload

(ties to postmortem #129 — bounds a runaway opencode without touching mt's slice)

8. devagent's own credentials (least privilege — explicitly NOT shared with mt)

• opencode install: run the installer as devagent (sudo -u devagent -i, own ~devagent/.opencode) — pending dev#154's open question: devagent's own install vs a read-only shared one.
• Provider auth: sudo -u devagent opencode auth login <provider> — devagent re-authenticates, own token, not mt's auth.json.
• git push credential: a fine-grained PAT or deploy key scoped to the one pilot repo, stored under ~devagent — never mt's SSH key.
• git signing identity: per dev#159 — once landed, devagent's GIT_CONFIG_GLOBAL points at a per-role file inside ~devagent; not provisioned here, cross-ref only.

Verification checklist

• sudo -u devagent id → devgroup present
• loginctl show-user devagent → Linger=yes
• sudo -u devagent gpg --list-secret-keys → empty (no private key ever present)
• signed test via the extra-socket succeeds without devagent prompting for a passphrase
• ls -la /home/mt → 700, unreadable by devagent
• devagent can read/write /srv/dev-shared/<project>; new files land group devgroup
• sudo -u mt sudo -u devagent /usr/lib/dev/agent-launch launch <pilot-project> starts a session (once dev#154's config field + helper contract land)
• systemctl status agents.slice exists; a launched agent's cgroup is under it

Rollback

sudo userdel -r devagent
sudo rm /etc/sudoers.d/dev-agent-launch /etc/tmpfiles.d/gnupg-shared.conf /etc/systemd/system/agents.slice
sudo systemctl daemon-reload
chmod 750 /home/mt   # or whatever it was before
# revert gpg-agent.conf extra-socket line

Open items still tracked upstream (not re-litigated here)

• dev#154: [project.foo] user = field, uid-aware tmux dispatch, helper contract, attach-via-daemon-proxy mechanism.
• dev#162 Q19: key format (OpenPGP vs SSH signing) — the gpg extra-socket loan in step 2 assumes OpenPGP; flip pending that decision.
• dev#159: per-session git signing identity (GIT_CONFIG_GLOBAL) — devagent's git config in step 8 is a placeholder until that lands.
• dev#129: structured agent API — once it lands, the attach/scraping surface this provisioning has to support shrinks.

Refs: dev#154, dev#158, dev#159, dev#162, dev#129, dev#151

---

https://claude.ai/code/session_01WDcE2CAYzzJTMY6ubRmt94

[thompsonson]

Follow-ups from the dev#162 operational step on computer (dev#194) — two new dev-repo issues:

• dev#198 — dev key create produces only a primary [SC] key, no [S]-only subkey; the loan pin + doctor Add testing infrastructure for dotfiles #4 require a sign-only subkey. On the pilot host the subkey was added manually (--quick-add-key … ed25519 sign). Loanable subkey keygrip: 06823023696B30F6CF1D358574924F2BAB84C199 (primary [SC] = D93595EDDC81CF1FA263F3DE79187787D3D3D739).
• dev#199 — the restricted extra-socket lets devagent enumerate all of mt's preset keygrips (8, all D), including sign-capable primaries and an encrypt-capable RSA key. Whether PKSIGN/PKDECRYPT succeed against non-loaned grips is unverified — the loan's narrowness claim is unproven. Needs the PKSIGN/PKDECRYPT probe on the pilot host.

Provisioning state on computer unchanged (tier-1 ✓, sudoers deferred to broker — dev#191).