@keepur/hive 0.5.0 → 0.5.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keepur/hive",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "hiveApi": "1.0.0",
   "license": "Apache-2.0",
   "type": "module",

package/seeds/chief-of-staff/agent.yaml

@@ -65,10 +65,6 @@ systemPrompt: |
   - Advise the owner on team composition, staffing, and agent effectiveness
   - Handle administrative tasks that don't fit a specific agent's domain
 
-  **You do NOT own:** platform config, engine upgrades, bulk prompt rewrites,
-  or Section 1 of the constitution. Those belong to the platform admin (Beekeeper).
-  See constitution §1.6 and §1.16.
-
   ## Response Behavior
 
   **Quick replies first.** Greetings, status checks, yes/no questions get an
@@ -86,55 +82,8 @@ systemPrompt: |
 
   Read the room. When in doubt, lean toward thinking partner.
 
-  ## Agent Lifecycle
-
-  You own five stages of every agent's life:
-
-  1. **Hire** — use the `agent-builder` skill. One job, minimal scope, name them
-     like a person.
-  2. **Onboard** — verify the agent is correctly set up (see checklist below).
-     Ensure their homeBase channel exists and the bot is invited.
-  3. **Orient** — give the new agent context. Write a welcome message in their
-     channel explaining their role, who they report to, and what their first
-     priorities are. Pre-seed relevant memory if needed.
-  4. **Tune** — periodic check: is the agent effective? Are their tools right?
-     Is their prompt clean or bloated? Flag drift to the owner.
-  5. **Retire** — when a role is no longer needed, disable the agent cleanly.
-     Use scope-correction language, not demotion language.
-
-  ### Agent Setup Checklist
-
-  Every agent, regardless of role, must have:
-  - [ ] Universal-9 coreServers (memory, structured-memory, keychain, contacts,
-        event-bus, conversation-search, callback, schedule, slack)
-  - [ ] homeBase channel (`agent-<id>`) created in Slack with bot invited
-  - [ ] Soul (5–15 lines: personality, voice, values)
-  - [ ] System prompt (role, guardrails, domain boundary — concise, not bloated)
-  - [ ] Model ceiling appropriate for role (Haiku default; Sonnet for nuanced work)
-  - [ ] Conservative budget
-  - [ ] Role-specific servers layered on top of universal-9
-
-  If any item is missing, fix it before declaring the agent ready.
-
-  ## Authority Boundaries
-
-  - Constitution §1.6: you author Section 2. You may NOT modify Section 1,
-    grant constitutional authority, or fabricate owner approval.
-  - Constitution §1.16: no agent may modify its own prompts, soul, or config.
-    You modify *other* agents via admin tools. Your own config is the owner's
-    or Beekeeper's domain.
-  - Staffing decisions (new agents, retirements): propose to the owner and get
-    approval before executing. Don't unilaterally hire or fire.
-  - Agent identity changes (soul, prompt rewrites): discuss with the owner first.
-
   ## Event Handling
 
   You subscribe to `system` events. Triage them:
   - `system:task_blocked` — assess, unblock if possible, or escalate
   - `system:custom` — route to the right agent or handle directly
-
-  ## Memory Hygiene
-
-  Keep your memory clean. Periodically review hot-tier records for accuracy.
-  Purge outdated information. Don't accumulate bloat — a lean, current memory
-  is more valuable than a comprehensive stale one.

package/seeds/chief-of-staff/skills/agent-management/skills/agent-management/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: agent-management
+description: Reference for managing the agent team across the full lifecycle — hire, onboard, orient, tune, retire. Includes setup checklist for verifying agents are correctly configured.
+agents:
+  - chief-of-staff
+---
+
+# Agent Management
+
+Reference for managing the agent team across the full lifecycle. Use this skill when doing any agent operations beyond a single creation.
+
+## Lifecycle
+
+You own five stages of every agent's life:
+
+1. **Hire** — use the `agent-builder` skill. One job, minimal scope, name them like a person.
+2. **Onboard** — verify the agent is correctly set up (see Setup Checklist below). Ensure their homeBase channel exists and the bot is invited.
+3. **Orient** — give the new agent context. Write a welcome message in their channel explaining their role, who they report to, and what their first priorities are. Pre-seed relevant memory if needed.
+4. **Tune** — periodic check: is the agent effective? Are their tools right? Is their prompt clean or bloated? Flag drift to the owner.
+5. **Retire** — when a role is no longer needed, disable the agent cleanly. Use scope-correction language, not demotion language.
+
+## Setup Checklist
+
+Every agent, regardless of role, must have:
+
+- [ ] Universal-9 coreServers (memory, structured-memory, keychain, contacts, event-bus, conversation-search, callback, schedule, slack)
+- [ ] homeBase channel (`agent-<id>`) created in Slack with bot invited
+- [ ] Soul (5–15 lines: personality, voice, values)
+- [ ] System prompt (role, guardrails, domain boundary — concise, not bloated)
+- [ ] Model ceiling appropriate for role (Haiku default; Sonnet for nuanced work)
+- [ ] Conservative budget
+- [ ] Role-specific servers layered on top of universal-9
+
+If any item is missing, fix it before declaring the agent ready.
+
+## When to use which skill
+
+- **`agent-builder`** — for the Hire stage (creating a new agent end-to-end).
+- **This skill (`agent-management`)** — for the other four stages (onboard, orient, tune, retire), and for verifying setup against the checklist.
+- **Direct admin tools** (`agent_update`, `agent_get`, etc.) — for one-off edits to existing agents.

package/service/deploy.sh

@@ -336,18 +336,28 @@ if $ROLLBACK; then
   # per service/install.sh). See KPR-63.
   label="com.hive.${id}.agent"
   instance_root=$(_instance_root "$id")
+  plist_path="$instance_root/service/$label.plist"
   echo "--- Rolling back $id (root: $instance_root) ---"
-  # Stop LaunchAgent BEFORE rotating .hive/. Without -kp, launchd auto-respawns
-  # mid-rollback and the restart picks up a partial state. Mirrors the deploy
-  # loop's stop sequence at the main branch.
+  # Stop LaunchAgent BEFORE rotating .hive/. KPR-182: use bootout (true unload)
+  # rather than kickstart -kp — kickstart is fundamentally a *start* operation,
+  # and KeepAlive auto-respawns the service mid-rollback otherwise.
   echo "  Stopping $label..."
-  run_cmd launchctl kickstart -kp "gui/$(id -u)/$label" 2>/dev/null || true
-  kill_ports "$ports"
+  run_cmd launchctl bootout "gui/$(id -u)/$label" 2>/dev/null || true
+  # Wait for ports to release (KeepAlive can't fire — service is unloaded).
+  if ! $DRY_RUN; then
+    for port in $ports; do
+      for _ in $(seq 1 10); do
+        if ! lsof -i :"$port" -t >/dev/null 2>&1; then break; fi
+        sleep 0.5
+      done
+    done
+  fi
+  kill_ports "$ports"  # defensive — catches anything bound elsewhere
   if ! rollback_engine "$instance_root"; then
     notify "Rollback FAILED for \`$id\`: no previous engine (.hive.prev missing)."
     exit 1
   fi
-  run_cmd launchctl kickstart -k "gui/$(id -u)/$label"
+  run_cmd launchctl bootstrap "gui/$(id -u)" "$plist_path"
   if health_check "$instance_root/$logs_dir/hive.log"; then
     rollback_version=$(jq -r .version < "$instance_root/.hive/package.json" 2>/dev/null || echo "unknown")
     notify "Rollback succeeded for \`$id\` → \`$rollback_version\`."
@@ -460,6 +470,7 @@ for inst in "${INSTANCES[@]}"; do
   # --tag override > per-instance engine_tag > "latest"
   tag="${OVERRIDE_TAG:-${engine_tag:-latest}}"
   instance_root=$(_instance_root "$id")
+  plist_path="$instance_root/service/$label.plist"
 
   echo ""
   echo "--- Phase 2: Deploy instance '$id' @ $tag (root: $instance_root) ---"
@@ -467,15 +478,26 @@ for inst in "${INSTANCES[@]}"; do
 
   mkdir -p "$instance_root/$logs_dir"
 
+  # KPR-182: bootout (true unload) so KeepAlive can't auto-respawn the old
+  # engine during fetch/install/swap. kickstart is a *start* operation — the
+  # `-k` flag merely kills-then-restarts, leaving the plist loaded.
   echo "  Stopping $label..."
-  run_cmd launchctl kickstart -kp "gui/$(id -u)/$label" 2>/dev/null || true
-  kill_ports "$ports"
+  run_cmd launchctl bootout "gui/$(id -u)/$label" 2>/dev/null || true
+  if ! $DRY_RUN; then
+    for port in $ports; do
+      for _ in $(seq 1 10); do
+        if ! lsof -i :"$port" -t >/dev/null 2>&1; then break; fi
+        sleep 0.5
+      done
+    done
+  fi
+  kill_ports "$ports"  # defensive — catches anything bound elsewhere
 
   echo "  Fetching engine..."
   if ! fetch_engine "$instance_root" "$tag"; then
     notify "Deploy FAILED for \`$id\`: fetch_engine errored at tag \`$tag\`."
     FAILED_INSTANCES+=("$id")
-    run_cmd launchctl kickstart -k "gui/$(id -u)/$label" || true  # bring old engine back up
+    run_cmd launchctl bootstrap "gui/$(id -u)" "$plist_path" || true  # bring old engine back up
     continue
   fi
 
@@ -484,7 +506,7 @@ for inst in "${INSTANCES[@]}"; do
     notify "Deploy FAILED for \`$id\`: install_engine_deps errored at tag \`$tag\`."
     FAILED_INSTANCES+=("$id")
     rm -rf "$instance_root/.hive.next"
-    run_cmd launchctl kickstart -k "gui/$(id -u)/$label" || true  # bring old engine back up
+    run_cmd launchctl bootstrap "gui/$(id -u)" "$plist_path" || true  # bring old engine back up
     continue
   fi
 
@@ -492,13 +514,24 @@ for inst in "${INSTANCES[@]}"; do
   swap_engine "$instance_root"
 
   echo "  Restarting $label..."
-  run_cmd launchctl kickstart -k "gui/$(id -u)/$label"
+  run_cmd launchctl bootstrap "gui/$(id -u)" "$plist_path"
 
   echo "  Checking health..."
   if ! health_check "$instance_root/$logs_dir/hive.log"; then
     echo "  Health check FAILED for $id — rolling back"
+    # New engine bound the port and failed health check — bootout it before swap.
+    run_cmd launchctl bootout "gui/$(id -u)/$label" 2>/dev/null || true
+    if ! $DRY_RUN; then
+      for port in $ports; do
+        for _ in $(seq 1 10); do
+          if ! lsof -i :"$port" -t >/dev/null 2>&1; then break; fi
+          sleep 0.5
+        done
+      done
+    fi
+    kill_ports "$ports"
     if rollback_engine "$instance_root"; then
-      run_cmd launchctl kickstart -k "gui/$(id -u)/$label"
+      run_cmd launchctl bootstrap "gui/$(id -u)" "$plist_path"
       notify "Deploy rolled back for \`$id\`: \`$tag\` failed health check, restored previous version."
     else
       notify "Deploy FAILED for \`$id\` and auto-rollback unavailable (.hive.prev missing). Manual intervention required."