fix(ansible): replace steward key on reprovision + distinct agent update path

Provisioning review corrections + the matching frontend, plus breadcrumb
header integration.

- provision.yml: authorize the managed pubkey with a regexp match on the
  ' steward-managed' comment so rotating the key REPLACES the host's steward
  key in place instead of stacking a second authorized entry. Hand-added keys
  (other comments) are untouched.
- update.yml (new): refresh agent.py + restart only. Does NOT rotate the token
  or rewrite /etc/steward-agent.conf — the host keeps its identity. Asserts the
  agent is already installed and fails clearly otherwise.
- host_agent /update route: runs update.yml as the managed steward user (no
  token minting). Token rotation stays a deliberate action.
- settings/ansible/generate-key honors a safe relative `next` redirect, so an
  inline trigger elsewhere returns to its page.
- Host Agents settings: reworked into a clear lifecycle — an intro card that
  explains it runs Ansible to deploy the agent (+ inline "generate managed key"
  warning/trigger when none exists), then three labelled cards: 1 Provision,
  2 Install/enroll, 3 Update. Each explains what it does.
- base.html: breadcrumb now renders as a kicker line directly above the page
  title (moved below alerts, tightened margin) so nested and top-level views
  share one consistent header.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

plugins/host_agent/routes.py

@@ -809,3 +809,38 @@ async def provision_via_ansible():
     if err:
         return _error(400, "provision_failed", err)
     return redirect(url_for("ansible.run_detail", run_id=run.id))
+
+
+@host_agent_bp.post("/update")
+@require_role(UserRole.admin)
+async def update_via_ansible():
+    """Refresh agent.py on already-installed hosts via the bundled update
+    playbook. Connects as the managed steward account — no token rotation, no
+    config rewrite (the host keeps its existing identity)."""
+    from steward.core.capabilities import has_capability, invoke_capability
+    from steward.ansible.sources import BUILTIN_SOURCE_NAME
+
+    if not has_capability("ansible.run_playbook"):
+        return _error(400, "ansible_unavailable", "Ansible is not available")
+
+    form = await request.form
+    scope = (form.get("inventory_scope", "") or "").strip()
+    if not (scope.startswith("steward:target:")
+            or scope.startswith("steward:group:")
+            or scope == "steward:all"):
+        return _error(400, "bad_scope", "Choose a target or group")
+
+    url = public_base_url(request)
+    actor_role = UserRole(session.get("user_role", "viewer"))
+    run, _source, err = await invoke_capability(
+        "ansible.run_playbook", actor_role,
+        current_app._get_current_object(),  # type: ignore[attr-defined]
+        source_name=BUILTIN_SOURCE_NAME,
+        playbook_path="host_agent/update.yml",
+        inventory_scope=scope,
+        params={"extra_vars": [f"steward_url={url}"]},
+        triggered_by=session.get("user_id"),
+    )
+    if err:
+        return _error(400, "update_failed", err)
+    return redirect(url_for("ansible.run_detail", run_id=run.id))

plugins/host_agent/templates/settings_list.html

@@ -31,41 +31,63 @@
 </div>
 
 {% if ansible_available %}
+{% set scope_select %}
+        <label>Target</label>
+        <select name="inventory_scope" required>
+          {% for g in deploy_groups %}<option value="steward:group:{{ g.id }}">Group: {{ g.name }}</option>{% endfor %}
+          {% for t in deploy_targets %}<option value="steward:target:{{ t.id }}">Target: {{ t.name }}</option>{% endfor %}
+        </select>
+{% endset %}
+
 <div class="card">
-  <h3 style="margin-bottom:0.4rem;">Provision a fresh host</h3>
+  <h3 style="margin-bottom:0.4rem;">Agent lifecycle via Ansible</h3>
-  <p style="font-size:0.82rem;color:var(--text-muted);margin-bottom:0.75rem;">
+  <p style="font-size:0.82rem;color:var(--text-muted);margin-bottom:0.6rem;">
-    First contact for a host Steward can't yet reach by key. Creates a
+    These actions run bundled <strong>Ansible playbooks</strong> to deploy and maintain the
-    <code>steward</code> login account with passwordless sudo, installs the managed
+    Steward monitoring agent on your <a href="/ansible/inventory/targets">inventory hosts</a>.
-    key, then installs the agent — over a one-time bootstrap password (used for this
+    Steward generates each host's API token automatically and connects over SSH as the managed
-    run only, never stored). After this, use <strong>Deploy</strong> below for updates.
+    <code>steward</code> account — you'll be dropped into the live Ansible run to watch it.
   </p>
+
   {% if not managed_key_set %}
-  <p style="font-size:0.85rem;color:var(--text-dim);">
+  <div style="background:color-mix(in srgb,var(--yellow) 12%,var(--bg-elevated));
-    No managed key yet. Generate one under <a href="/settings/ansible/">Settings → Ansible</a> first.
+              border:1px solid color-mix(in srgb,var(--yellow) 35%,var(--border));
-  </p>
+              border-radius:6px;padding:0.7rem 0.9rem;display:flex;align-items:center;
+              gap:0.8rem;flex-wrap:wrap;">
+    <span style="color:var(--yellow);">⚠</span>
+    <span style="font-size:0.84rem;flex:1;min-width:14rem;">
+      No managed SSH key yet — Steward needs one to log into hosts as <code>steward</code>.
+    </span>
+    <form method="post" action="/settings/ansible/generate-key" style="margin:0;">
+      <input type="hidden" name="next" value="/plugins/host_agent/settings/">
+      <button type="submit" class="btn btn-sm">Generate managed key</button>
+    </form>
+  </div>
   {% elif not (deploy_targets or deploy_groups) %}
-  <p style="font-size:0.85rem;color:var(--text-dim);">
+  <p style="font-size:0.85rem;color:var(--text-dim);margin:0;">
     No Ansible inventory targets yet. Add some under <a href="/ansible/inventory/targets">Ansible → Inventory</a>.
   </p>
-  {% else %}
+  {% endif %}
+</div>
+
+{% if managed_key_set and (deploy_targets or deploy_groups) %}
+<div class="card">
+  <h3 style="margin-bottom:0.4rem;">1 · Provision a fresh host</h3>
+  <p style="font-size:0.82rem;color:var(--text-muted);margin-bottom:0.75rem;">
+    First contact for a brand-new host. Connects with a one-time <strong>bootstrap</strong>
+    user + password (used for this run only, never stored), creates the <code>steward</code>
+    login account with passwordless sudo, installs the managed SSH key, then installs the
+    agent. Run this once per host.
+  </p>
   <form method="post" action="/plugins/host_agent/provision"
         style="display:flex;gap:0.75rem;align-items:flex-end;flex-wrap:wrap;">
-    <div class="form-group" style="margin-bottom:0;">
+    <div class="form-group" style="margin-bottom:0;">{{ scope_select }}</div>
-      <label>Target</label>
-      <select name="inventory_scope" required>
-        {% for g in deploy_groups %}<option value="steward:group:{{ g.id }}">Group: {{ g.name }}</option>{% endfor %}
-        {% for t in deploy_targets %}<option value="steward:target:{{ t.id }}">Target: {{ t.name }}</option>{% endfor %}
-      </select>
-    </div>
     <div class="form-group" style="margin-bottom:0;">
       <label>Bootstrap user</label>
-      <input type="text" name="bootstrap_user" required placeholder="root" style="width:9rem;"
+      <input type="text" name="bootstrap_user" required placeholder="root" style="width:9rem;" autocomplete="off">
-             autocomplete="off">
     </div>
     <div class="form-group" style="margin-bottom:0;">
       <label>Bootstrap password</label>
-      <input type="password" name="bootstrap_password" required style="width:11rem;"
+      <input type="password" name="bootstrap_password" required style="width:11rem;" autocomplete="new-password">
-             autocomplete="new-password">
     </div>
     <div class="form-group" style="margin-bottom:0;">
       <label>Report interval (s)</label>
@@ -73,37 +95,40 @@
     </div>
     <button type="submit" class="btn">Provision</button>
   </form>
-  {% endif %}
 </div>
 
 <div class="card">
-  <h3 style="margin-bottom:0.4rem;">Deploy via Ansible</h3>
+  <h3 style="margin-bottom:0.4rem;">2 · Install / enroll agent</h3>
   <p style="font-size:0.82rem;color:var(--text-muted);margin-bottom:0.75rem;">
-    Install (or update) the agent on Ansible inventory hosts in one run — no per-host <code>curl | sh</code>.
+    For a host that's already provisioned (has the <code>steward</code> account) but has no
-    A fresh token is minted per host and injected into the run; existing agents are rotated to the new token.
+    agent yet — or to re-enroll one. Connects as <code>steward</code> with the managed key,
+    mints a fresh token, and installs the agent. No <code>curl | sh</code> needed.
   </p>
-  {% if not (deploy_targets or deploy_groups) %}
-  <p style="font-size:0.85rem;color:var(--text-dim);">
-    No Ansible inventory targets yet. Add some under <a href="/ansible/browse">Ansible → Browse</a>.
-  </p>
-  {% else %}
   <form method="post" action="/plugins/host_agent/deploy"
         style="display:flex;gap:0.75rem;align-items:flex-end;flex-wrap:wrap;">
-    <div class="form-group" style="margin-bottom:0;">
+    <div class="form-group" style="margin-bottom:0;">{{ scope_select }}</div>
-      <label>Target</label>
-      <select name="inventory_scope" required>
-        {% for g in deploy_groups %}<option value="steward:group:{{ g.id }}">Group: {{ g.name }}</option>{% endfor %}
-        {% for t in deploy_targets %}<option value="steward:target:{{ t.id }}">Target: {{ t.name }}</option>{% endfor %}
-      </select>
-    </div>
     <div class="form-group" style="margin-bottom:0;">
       <label>Report interval (s)</label>
       <input type="number" name="agent_interval" value="30" min="5" style="width:7rem;">
     </div>
-    <button type="submit" class="btn">Deploy</button>
+    <button type="submit" class="btn">Install</button>
   </form>
-  {% endif %}
 </div>
+
+<div class="card">
+  <h3 style="margin-bottom:0.4rem;">3 · Update agents</h3>
+  <p style="font-size:0.82rem;color:var(--text-muted);margin-bottom:0.75rem;">
+    Refresh the agent binary on hosts already running it. Connects as <code>steward</code>
+    with the managed key and restarts the service — the token and config are left untouched,
+    so identity is preserved.
+  </p>
+  <form method="post" action="/plugins/host_agent/update"
+        style="display:flex;gap:0.75rem;align-items:flex-end;flex-wrap:wrap;">
+    <div class="form-group" style="margin-bottom:0;">{{ scope_select }}</div>
+    <button type="submit" class="btn">Update</button>
+  </form>
+</div>
+{% endif %}
 {% endif %}
 
 <div class="card-flush">

steward/ansible/bundled/host_agent/provision.yml

@@ -50,9 +50,13 @@
         group: "{{ steward_user }}"
         mode: "0700"
 
-    - name: Authorize the managed public key
+    - name: Authorize the managed public key (replace any prior steward-managed key)
       ansible.builtin.lineinfile:
         path: "/home/{{ steward_user }}/.ssh/authorized_keys"
+        # Match on the ' steward-managed' comment so a rotated key REPLACES the
+        # old one in place rather than stacking a second authorized key. Any
+        # keys the operator added by hand (different comment) are left untouched.
+        regexp: ' steward-managed$'
         line: "{{ steward_pubkey }}"
         create: true
         owner: "{{ steward_user }}"

steward/ansible/bundled/host_agent/update.yml

@@ -0,0 +1,47 @@
+---
+# Update an already-installed Steward host agent: refresh agent.py and restart.
+#
+# Deliberately does NOT touch the registration token or /etc/steward-agent.conf
+# — the host already has a working token, so an update leaves identity alone and
+# only swaps the agent binary. Connects as the managed `steward` account (set
+# globally as the SSH user); no bootstrap password or token injection needed.
+#
+# For a fresh host with no agent, use provision.yml (new host) or install.yml
+# (already-provisioned host) instead — those mint and install the token.
+- name: Update Steward host agent
+  hosts: all
+  become: true
+  gather_facts: false
+  vars:
+    steward_url: ""
+  tasks:
+    - name: Require steward_url
+      ansible.builtin.assert:
+        that:
+          - steward_url | length > 0
+        fail_msg: "Pass steward_url as an extra-var (the Update action sets it)."
+
+    - name: Confirm the agent is already installed
+      ansible.builtin.stat:
+        path: /usr/local/lib/steward-agent/agent.py
+      register: agent_file
+
+    - name: Fail clearly if the agent is missing
+      ansible.builtin.fail:
+        msg: "No agent at /usr/local/lib/steward-agent — provision or install this host first."
+      when: not agent_file.stat.exists
+
+    - name: Refresh agent.py
+      ansible.builtin.get_url:
+        url: "{{ steward_url }}/plugins/host_agent/agent.py"
+        dest: /usr/local/lib/steward-agent/agent.py
+        mode: "0755"
+        force: true
+      notify: restart steward-agent
+
+  handlers:
+    - name: restart steward-agent
+      ansible.builtin.systemd:
+        name: steward-agent
+        state: restarted
+        daemon_reload: true

steward/settings/routes.py

@@ -197,6 +197,7 @@ async def ansible_generate_key():
     """
     from steward.core.crypto import generate_ssh_keypair
 
+    form = await request.form
     private_pem, public_line = generate_ssh_keypair()
     async with current_app.db_sessionmaker() as db:
         async with db.begin():
@@ -205,6 +206,10 @@ async def ansible_generate_key():
     await _reload_app_config()
     await log_audit(current_app, session.get("user_id"), session.get("username", ""),
                     "settings.saved", detail={"section": "ansible.managed_key"})
+    # Allow the inline trigger on other pages (e.g. Host Agents) to return there.
+    nxt = (form.get("next", "") or "").strip()
+    if nxt.startswith("/") and not nxt.startswith("//"):
+        return redirect(nxt)
     return redirect(url_for("settings.ansible"))
 
 

steward/templates/base.html

@@ -146,7 +146,9 @@ textarea { resize: vertical; }
 .empty { color: var(--text-muted); font-size: 0.9rem; padding: 2rem; text-align: center; }
 
 /* Breadcrumbs */
-.breadcrumb { display:flex; align-items:center; flex-wrap:wrap; gap:0.35rem; font-size:0.8rem; color:var(--text-dim); margin-bottom:1rem; }
+/* Breadcrumb renders as a kicker line tucked directly above the page header
+   (.page-title), so nested and top-level views share one consistent header. */
+.breadcrumb { display:flex; align-items:center; flex-wrap:wrap; gap:0.35rem; font-size:0.78rem; color:var(--text-dim); margin:0 0 0.45rem; }
 .breadcrumb a { color:var(--text-muted); }
 .breadcrumb a:hover { color:var(--text); }
 .breadcrumb-sep { color:var(--border-mid); }
@@ -235,7 +237,6 @@ function setTimeRange(val) {
 </script>
 
     <main>
-        {% block breadcrumb %}{% endblock %}
         {% if plugin_failures and session.user_role == 'admin' %}
         <div style="background:color-mix(in srgb,var(--yellow) 12%,var(--bg-elevated));
                     border:1px solid color-mix(in srgb,var(--yellow) 35%,var(--border));
@@ -253,6 +254,7 @@ function setTimeRange(val) {
         {% if error %}
         <div class="alert alert-error">{{ error }}</div>
         {% endif %}
+        {% block breadcrumb %}{% endblock %}
         {% block content %}{% endblock %}
     </main>