From 3d919b596fcfca4d249790367a5e5052d053f99c Mon Sep 17 00:00:00 2001
From: atlas <atlas@hyperhive.local>
Date: Wed, 8 Jul 2026 23:27:48 +0200
Subject: [PATCH 1/9] =?UTF-8?q?feat(#2290):=20split=20ensure=5Fruntime=20?=
 =?UTF-8?q?=E2=80=94=20dirs=20to=20lifecycle,=20listeners=20to=20mcp=5Fsoc?=
 =?UTF-8?q?kets=20supervisor?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- lifecycle::ensure_agent_runtime_dir(name): pure filesystem op, no
  Coordinator dep. Creates /run/hyperhive/agents/<name> without touching
  the MCP listener map.

- workers/mcp_sockets::spawn_poll(coord): 10 s reconcile loop (same shape
  as agent_sockets::spawn_poll). Converges 'agent running => MCP listener
  bound'. First tick is immediate so hive-c0re restarts re-register all
  running agents without waiting a full interval. Fixes the dead-listener-
  after-daemon-restart gap.

- All ensure_runtime() call sites updated:
  - Prebuild/Swap/WriteDropin: Coordinator::agent_dir() (pure, no IO)
  - Reconcile-Start: ensure_agent_runtime_dir + agent_dir (dir may be
    missing after reboot; listener deferred to supervisor)
  - run_create / handle_spawn: ensure_agent_runtime_dir + register_agent
    (eager on first spawn so socket ready before harness first turn)
  - apply_commit / merge_config_pr: ensure_agent_runtime_dir + agent_dir
  - Manager (auto_update): ensure_agent_runtime_dir + agent_dir
    (manager has no MCP listener; socket_server::start_manager owns it)

- ensure_runtime() retained in Coordinator with updated doc pointing at
  the preferred split form. No callers remain outside tests.
---
 hive-c0re/src/actions.rs             |  9 ++++-
 hive-c0re/src/coordinator.rs         | 29 ++++++++------
 hive-c0re/src/job_queue/exec.rs      | 31 +++++++++++----
 hive-c0re/src/lib.rs                 |  2 +-
 hive-c0re/src/lifecycle/mod.rs       | 17 ++++++++
 hive-c0re/src/main.rs                | 11 +++++-
 hive-c0re/src/server.rs              |  7 +++-
 hive-c0re/src/workers/auto_update.rs |  5 ++-
 hive-c0re/src/workers/mcp_sockets.rs | 59 ++++++++++++++++++++++++++++
 hive-c0re/src/workers/mod.rs         |  7 ++--
 10 files changed, 147 insertions(+), 30 deletions(-)
 create mode 100644 hive-c0re/src/workers/mcp_sockets.rs

diff --git a/hive-c0re/src/actions.rs b/hive-c0re/src/actions.rs
index d89defea..e734c224 100644
--- a/hive-c0re/src/actions.rs
+++ b/hive-c0re/src/actions.rs
@@ -159,7 +159,11 @@ pub async fn run_approval_apply_commit(
     approval_id: i64,
 ) -> Result<()> {
     let approval = fetch_approval_for_worker(coord, approval_id, ApprovalKind::ApplyCommit)?;
-    let agent_dir = coord.ensure_runtime(&approval.agent)?;
+    // Create the bind-mount source dir (first-spawn may not have it yet).
+    // MCP listener registration is deferred to mcp_sockets::spawn_poll
+    // which fires within 10 s of the container coming up.
+    lifecycle::ensure_agent_runtime_dir(&approval.agent)?;
+    let agent_dir = Coordinator::agent_dir(&approval.agent);
     let applied_dir = Coordinator::agent_applied_dir(&approval.agent);
     coord.set_queue_step(queue_entry_id, "apply commit");
     let (result, terminal_tag, is_first_spawn) =
@@ -192,7 +196,8 @@ pub async fn run_approval_merge_config_pr(
     approval_id: i64,
 ) -> Result<()> {
     let approval = fetch_approval_for_worker(coord, approval_id, ApprovalKind::MergeConfigPr)?;
-    let agent_dir = coord.ensure_runtime(&approval.agent)?;
+    lifecycle::ensure_agent_runtime_dir(&approval.agent)?;
+    let agent_dir = Coordinator::agent_dir(&approval.agent);
     let applied_dir = Coordinator::agent_applied_dir(&approval.agent);
     coord.set_queue_step(queue_entry_id, "merge config pr");
     let (result, terminal_tag) =
diff --git a/hive-c0re/src/coordinator.rs b/hive-c0re/src/coordinator.rs
index 97d984e9..d2473f3c 100644
--- a/hive-c0re/src/coordinator.rs
+++ b/hive-c0re/src/coordinator.rs
@@ -545,14 +545,11 @@ impl Coordinator {
         }
     }
 
-    /// Assemble the per-agent filesystem paths for `name`. The caller
-    /// must supply `agent_dir` (from `ensure_runtime`) since that
-    /// creates the tmpfs entry on first call. All other paths are
-    /// derived statically from `name`.
-    ///
-    /// ```ignore
-    /// let paths = Coordinator::agent_paths(name, coord.ensure_runtime(name)?);
-    /// ```
+    /// Assemble the per-agent filesystem paths for `name`. `agent_dir`
+    /// is the runtime directory (`/run/hyperhive/agents/<name>`), obtained
+    /// from `Coordinator::agent_dir(name)` (pure path) or from
+    /// `lifecycle::ensure_agent_runtime_dir` + `agent_dir` when the dir
+    /// must be created. All other paths are derived statically from `name`.
     #[must_use]
     pub fn agent_paths(name: &str, agent_dir: PathBuf) -> AgentPaths {
         AgentPaths {
@@ -1453,11 +1450,17 @@ impl Coordinator {
         Self::agent_dir(name).join("mcp.sock")
     }
 
-    /// Ensure a runtime dir + (for sub-agents) per-agent socket exists. For
-    /// the manager, `socket_server::start_manager` owns the socket — just return
-    /// the dir. For sub-agents this is `register_agent` (creates a fresh
-    /// listener bound to `socket_path(name)`). Source directory of the
-    /// `/run/hive/mcp.sock` bind that ends up in `set_nspawn_flags`.
+    /// Ensure a runtime dir + (for sub-agents) per-agent socket exists.
+    ///
+    /// **Prefer the split form:**
+    /// - dir creation → `lifecycle::ensure_agent_runtime_dir(name)`
+    /// - listener registration → `register_agent(name)` (eagerly, on first
+    ///   spawn) or leave it to `mcp_sockets::spawn_poll` (reconcile within
+    ///   10 s, safe for the start + rebuild paths where the container
+    ///   takes longer than that to boot).
+    ///
+    /// This method is kept as a convenience shim for any remaining callers
+    /// that need the combined semantics in one call.
     pub fn ensure_runtime(self: &Arc<Self>, name: &str) -> Result<PathBuf> {
         if name == crate::lifecycle::MANAGER_NAME {
             let dir = Self::agent_dir(name);
diff --git a/hive-c0re/src/job_queue/exec.rs b/hive-c0re/src/job_queue/exec.rs
index 9a229459..ad401278 100644
--- a/hive-c0re/src/job_queue/exec.rs
+++ b/hive-c0re/src/job_queue/exec.rs
@@ -97,9 +97,10 @@ async fn run_prebuild(
     relock: bool,
 ) -> Result<NodeOutput> {
     let name = &claim.agent;
-    let agent_dir = coord
-        .ensure_runtime(name)
-        .with_context(|| format!("ensure_runtime {name}"))?;
+    // Prebuild runs while the agent is still up — the runtime dir and
+    // MCP listener already exist. Use the pure path accessor; no need
+    // to re-register the listener (the mcp_sockets supervisor owns that).
+    let agent_dir = Coordinator::agent_dir(name);
     let hive = coord.hive_env();
     let paths = Coordinator::agent_paths(name, agent_dir);
     crate::lifecycle::prepare_rebuild_dirs(name, &paths).await?;
@@ -131,7 +132,9 @@ async fn run_prebuild(
 /// `Reconcile` runs after this node terminal ok *or* fail.
 async fn run_swap(coord: &Arc<Coordinator>, claim: &Claim, ctx: &Ctx<'_>) -> Result<NodeOutput> {
     let name = &claim.agent;
-    let agent_dir = coord.ensure_runtime(name)?;
+    // Swap runs on an already-existing (stopped) container — runtime dir
+    // and listener were created earlier. Pure path accessor suffices.
+    let agent_dir = Coordinator::agent_dir(name);
     let hive = coord.hive_env();
     let paths = Coordinator::agent_paths(name, agent_dir);
     let result =
@@ -178,7 +181,12 @@ async fn run_swap(coord: &Arc<Coordinator>, claim: &Claim, ctx: &Ctx<'_>) -> Res
 /// build+create — no prebuild needed).
 async fn run_create(coord: &Arc<Coordinator>, claim: &Claim, ctx: &Ctx<'_>) -> Result<NodeOutput> {
     let name = &claim.agent;
-    let agent_dir = coord.ensure_runtime(name)?;
+    // First-spawn: create the bind-mount source dir (tmpfs — empty after
+    // reboot). Register the MCP listener eagerly so it's ready when the
+    // tail Reconcile starts the container and the harness connects.
+    crate::lifecycle::ensure_agent_runtime_dir(name)?;
+    coord.register_agent(name)?;
+    let agent_dir = Coordinator::agent_dir(name);
     let hive = coord.hive_env();
     let paths = Coordinator::agent_paths(name, agent_dir);
     ctx.step("nixos-container create");
@@ -254,7 +262,13 @@ async fn run_reconcile(
             // Prebuild/Swap nodes; the bare-Reconcile templates (boot
             // reconcile, plain start/restart) otherwise start with
             // nothing under /run and fail.
-            let agent_dir = coord.ensure_runtime(name)?;
+            //
+            // Dir creation is the pure-filesystem part (no Coordinator
+            // dep). The MCP listener is reconciled by mcp_sockets::spawn_poll
+            // whose first tick fires immediately on daemon start — the
+            // container boot takes longer than the 10 s interval anyway.
+            crate::lifecycle::ensure_agent_runtime_dir(name)?;
+            let agent_dir = Coordinator::agent_dir(name);
             let hive = coord.hive_env();
             let paths = Coordinator::agent_paths(name, agent_dir);
             crate::lifecycle::write_dropins(name, &hive, &paths).await?;
@@ -336,7 +350,10 @@ async fn run_drain(coord: &Arc<Coordinator>, claim: &Claim, ctx: &Ctx<'_>) -> Re
 /// `set_nspawn_flags` + `set_resource_limits` + daemon-reload.
 async fn run_write_dropin(coord: &Arc<Coordinator>, claim: &Claim) -> Result<NodeOutput> {
     let name = &claim.agent;
-    let agent_dir = coord.ensure_runtime(name)?;
+    // write_dropins only needs the path value to build AgentPaths; the
+    // dir doesn't need to exist at this point (created by ensure_runtime
+    // on the upstream Prebuild/Start node).
+    let agent_dir = Coordinator::agent_dir(name);
     let hive = coord.hive_env();
     let paths = Coordinator::agent_paths(name, agent_dir);
     crate::lifecycle::write_dropins(name, &hive, &paths).await?;
diff --git a/hive-c0re/src/lib.rs b/hive-c0re/src/lib.rs
index 3b20bd5e..c2156ed4 100644
--- a/hive-c0re/src/lib.rs
+++ b/hive-c0re/src/lib.rs
@@ -50,6 +50,6 @@ pub use stores::{
     approvals, audit_log, broker, build_logs, db, operator_questions, power, scheduled_prompts,
 };
 pub use workers::{
-    agent_sockets, auto_update, crash_watch, knowledge, reminder_scheduler,
+    agent_sockets, auto_update, crash_watch, knowledge, mcp_sockets, reminder_scheduler,
     scheduled_prompts_worker,
 };
diff --git a/hive-c0re/src/lifecycle/mod.rs b/hive-c0re/src/lifecycle/mod.rs
index cf91a945..1e325c2c 100644
--- a/hive-c0re/src/lifecycle/mod.rs
+++ b/hive-c0re/src/lifecycle/mod.rs
@@ -749,6 +749,23 @@ pub async fn sync_tmpfiles() {
     }
 }
 
+/// Ensure the per-agent runtime directory `/run/hyperhive/agents/<name>`
+/// exists. The directory is also written by `SyncAgentTmpfiles` (run at
+/// boot + spawn/destroy), but explicit creation in start/spawn paths guards
+/// against races where hive-c0re starts a container before tmpfiles.d has
+/// applied the new entry.
+///
+/// Pure filesystem op — no `Coordinator` dependency — so callers that only
+/// need the dir do not have to hold an `Arc<Coordinator>`.
+///
+/// # Errors
+/// Returns an error if `create_dir_all` fails.
+pub fn ensure_agent_runtime_dir(name: &str) -> Result<()> {
+    let dir = std::path::PathBuf::from(format!("/run/hyperhive/agents/{name}"));
+    std::fs::create_dir_all(&dir)
+        .with_context(|| format!("create agent runtime dir {}", dir.display()))
+}
+
 /// Build the per-line callback for `create_container_streaming` /
 /// `update_container_streaming`. Both ops share identical dispatch logic
 /// (stdout → info + `append_stdout`, stderr → warn + `append_stderr`); this
diff --git a/hive-c0re/src/main.rs b/hive-c0re/src/main.rs
index b9752362..f36f08be 100644
--- a/hive-c0re/src/main.rs
+++ b/hive-c0re/src/main.rs
@@ -13,8 +13,8 @@ use hive_sh4re::{HostRequest, HostResponse};
 use hive_c0re::coordinator::{Coordinator, HiveEnv, ServeConfig};
 use hive_c0re::{
     agent_sockets, auto_update, broker, client, crash_watch, dashboard, dashboard_events, forge,
-    job_queue, knowledge, matrix, migrate, reminder_scheduler, scheduled_prompts_worker, server,
-    socket_server,
+    job_queue, knowledge, matrix, migrate, mcp_sockets, reminder_scheduler,
+    scheduled_prompts_worker, server, socket_server,
 };
 
 #[derive(Parser)]
@@ -420,6 +420,13 @@ async fn cmd_serve(
     // is one stat per agent per tick.
     // See `docs/gateway.md::Per-agent unix-socket upstream`.
     agent_sockets::spawn_poll();
+    // MCP socket listener reconcile loop: every 10s re-registers any
+    // running agent that lost its host-side MCP listener (e.g. after a
+    // hive-c0re restart cleared /run/hyperhive/agents/). First tick fires
+    // immediately so restarts re-register all running agents without delay.
+    // Decouples listener registration from the start path — start only needs
+    // lifecycle::ensure_agent_runtime_dir; the supervisor converges the rest.
+    mcp_sockets::spawn_poll(coord.clone());
     // Reminder scheduler: drains due reminders + handles
     // file_path payload persistence. See reminder_scheduler.rs.
     reminder_scheduler::spawn(coord.clone());
diff --git a/hive-c0re/src/server.rs b/hive-c0re/src/server.rs
index f0913c85..5bb12604 100644
--- a/hive-c0re/src/server.rs
+++ b/hive-c0re/src/server.rs
@@ -202,7 +202,12 @@ async fn dispatch(req: &HostRequest, coord: Arc<Coordinator>) -> HostResponse {
 /// registration and notifying the manager on failure.
 async fn handle_spawn(coord: &Arc<Coordinator>, name: &str) -> Result<HostResponse> {
     tracing::info!(%name, "spawn");
-    let agent_dir = coord.ensure_runtime(name)?;
+    // Create the bind-mount source dir (pure filesystem, no Coordinator dep).
+    // MCP listener registration happens eagerly here (not deferred to the
+    // supervisor) so the socket is ready before the harness's first turn.
+    lifecycle::ensure_agent_runtime_dir(name)?;
+    coord.register_agent(name)?;
+    let agent_dir = Coordinator::agent_dir(name);
     let hive = coord.hive_env();
     let paths = Coordinator::agent_paths(name, agent_dir);
     match lifecycle::spawn(name, &hive, &paths).await {
diff --git a/hive-c0re/src/workers/auto_update.rs b/hive-c0re/src/workers/auto_update.rs
index 590ff450..b3c6fceb 100644
--- a/hive-c0re/src/workers/auto_update.rs
+++ b/hive-c0re/src/workers/auto_update.rs
@@ -153,7 +153,10 @@ pub async fn ensure_root_agent(coord: &Arc<Coordinator>) -> Result<()> {
         return Ok(());
     }
     tracing::info!("manager container missing — spawning");
-    let runtime = coord.ensure_runtime(MANAGER_NAME)?;
+    lifecycle::ensure_agent_runtime_dir(MANAGER_NAME)?;
+    // Manager has no MCP listener (socket_server::start_manager owns its
+    // socket); just need the dir + path value.
+    let runtime = Coordinator::agent_dir(MANAGER_NAME);
     let hive = coord.hive_env();
     let paths = Coordinator::agent_paths(MANAGER_NAME, runtime);
     lifecycle::spawn(MANAGER_NAME, &hive, &paths).await?;
diff --git a/hive-c0re/src/workers/mcp_sockets.rs b/hive-c0re/src/workers/mcp_sockets.rs
new file mode 100644
index 00000000..1808a66d
--- /dev/null
+++ b/hive-c0re/src/workers/mcp_sockets.rs
@@ -0,0 +1,59 @@
+//! MCP socket listener reconcile loop.
+//!
+//! Periodically checks that every running agent container has a bound
+//! MCP listener registered in the `Coordinator`. Any agent that is running
+//! but whose listener has gone (e.g. after a hive-c0re restart that cleared
+//! `/run/hyperhive/agents/`) gets re-registered automatically.
+//!
+//! Same shape as `agent_sockets::spawn_poll` — a simple 10 s tick loop that
+//! converges "agent container running ⇒ MCP listener bound". The self-healing
+//! guarantee means the start path no longer needs to call `register_agent`
+//! directly (though spawn still does for eagerness); callers only need
+//! `lifecycle::ensure_agent_runtime_dir` to create the bind-mount source.
+
+use std::sync::Arc;
+
+use crate::coordinator::Coordinator;
+
+/// Spawn the MCP socket listener reconcile loop.
+///
+/// Every 10 s the loop lists running agent containers and calls
+/// `register_agent` for any that lack a bound listener. The first tick fires
+/// immediately so hive-c0re restarts re-register all running agents without
+/// waiting a full interval.
+pub fn spawn_poll(coord: Arc<Coordinator>) {
+    tokio::spawn(async move {
+        let mut interval = tokio::time::interval(std::time::Duration::from_secs(10));
+        loop {
+            interval.tick().await;
+            reconcile_once(&coord).await;
+        }
+    });
+}
+
+async fn reconcile_once(coord: &Arc<Coordinator>) {
+    let running = match crate::lifecycle::list().await {
+        Ok(names) => names,
+        Err(e) => {
+            tracing::debug!(error = ?e, "mcp_sockets poll: failed to list agents");
+            return;
+        }
+    };
+    let registered = coord.list_agents();
+    for container in running {
+        let Some(name) = container.strip_prefix(crate::lifecycle::AGENT_PREFIX) else {
+            continue;
+        };
+        if !registered.contains(&name.to_owned()) {
+            if let Err(e) = coord.register_agent(name) {
+                tracing::warn!(
+                    agent = %name,
+                    error = ?e,
+                    "mcp_sockets poll: register_agent failed"
+                );
+            } else {
+                tracing::debug!(agent = %name, "mcp_sockets poll: registered missing listener");
+            }
+        }
+    }
+}
diff --git a/hive-c0re/src/workers/mod.rs b/hive-c0re/src/workers/mod.rs
index 98654ea3..75619f0b 100644
--- a/hive-c0re/src/workers/mod.rs
+++ b/hive-c0re/src/workers/mod.rs
@@ -1,12 +1,13 @@
 //! Background tasks and periodic sweeps: crash/login watcher, the
 //! reminder and scheduled-prompt delivery loops, boot-time auto-update
-//! reconcile, the agent-sockets.json writer loop, and knowledge-repo
-//! sync. Each submodule is re-exported at the crate root, so
-//! `crate::crash_watch::…` etc. keep working unchanged.
+//! reconcile, the agent-sockets.json writer loop, the MCP socket listener
+//! reconcile loop, and knowledge-repo sync. Each submodule is re-exported
+//! at the crate root, so `crate::crash_watch::…` etc. keep working unchanged.
 
 pub mod agent_sockets;
 pub mod auto_update;
 pub mod crash_watch;
 pub mod knowledge;
+pub mod mcp_sockets;
 pub mod reminder_scheduler;
 pub mod scheduled_prompts_worker;

From 15fc33d2e186c7bfc629596f938e41f20399ef1b Mon Sep 17 00:00:00 2001
From: atlas <atlas@hyperhive.local>
Date: Wed, 8 Jul 2026 23:59:19 +0200
Subject: [PATCH 2/9] style: rustfmt

---
 hive-c0re/src/main.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/hive-c0re/src/main.rs b/hive-c0re/src/main.rs
index f36f08be..42ca5687 100644
--- a/hive-c0re/src/main.rs
+++ b/hive-c0re/src/main.rs
@@ -13,7 +13,7 @@ use hive_sh4re::{HostRequest, HostResponse};
 use hive_c0re::coordinator::{Coordinator, HiveEnv, ServeConfig};
 use hive_c0re::{
     agent_sockets, auto_update, broker, client, crash_watch, dashboard, dashboard_events, forge,
-    job_queue, knowledge, matrix, migrate, mcp_sockets, reminder_scheduler,
+    job_queue, knowledge, matrix, mcp_sockets, migrate, reminder_scheduler,
     scheduled_prompts_worker, server, socket_server,
 };
 

From 950a13bc69d8958d50c1a2bf8debcb3631a5dcf0 Mon Sep 17 00:00:00 2001
From: atlas <atlas@hyperhive.local>
Date: Wed, 8 Jul 2026 23:31:30 +0200
Subject: [PATCH 3/9] =?UTF-8?q?feat(#2290):=20StartableAgent=20token=20?=
 =?UTF-8?q?=E2=80=94=20start=5Fwith=5Ffallback=20requires=20preamble=20pro?=
 =?UTF-8?q?of?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- lifecycle::StartableAgent: opaque token produced only by
  converge_start_preamble. #[must_use] with a hint to call
  start_with_fallback(token).

- lifecycle::converge_start_preamble(name, hive, paths): runs
  ensure_agent_runtime_dir + write_dropins, returns StartableAgent.
  The only way to obtain a token.

- lifecycle::start_with_fallback(token: StartableAgent): public API
  now requires the token. Callers that skip the preamble get a compile
  error, not a runtime outage.

- lifecycle::start_with_fallback_inner(name): private; used internally
  by rebuild_no_meta where the preamble is already enforced structurally
  (write_dropins was called on the line above).

- exec.rs ReconcileAction::Start: migrated to converge_start_preamble
  + start_with_fallback(token). The write_dropins + start_with_fallback
  two-step is now a single typed pipeline.
---
 hive-c0re/src/job_queue/exec.rs | 27 +++++++------------
 hive-c0re/src/lifecycle/mod.rs  | 48 +++++++++++++++++++++++++++++++--
 2 files changed, 56 insertions(+), 19 deletions(-)

diff --git a/hive-c0re/src/job_queue/exec.rs b/hive-c0re/src/job_queue/exec.rs
index ad401278..7e0b560c 100644
--- a/hive-c0re/src/job_queue/exec.rs
+++ b/hive-c0re/src/job_queue/exec.rs
@@ -253,27 +253,20 @@ async fn run_reconcile(
                 .transient
                 .is_none()
                 .then(|| coord.transient_guard(name, crate::coordinator::TransientKind::Starting));
-            // Converge the ephemeral host-side state before the start:
-            // `/run/hyperhive/agents/<name>` + `/run/hive-agent/<name>`
-            // (both nspawn bind sources — tmpfs, empty after a host
-            // reboot; nspawn refuses to start with a missing source)
-            // and the resource-limits drop-in under
-            // `/run/systemd/system/`. Rebuild DAGs get this from their
-            // Prebuild/Swap nodes; the bare-Reconcile templates (boot
-            // reconcile, plain start/restart) otherwise start with
-            // nothing under /run and fail.
-            //
-            // Dir creation is the pure-filesystem part (no Coordinator
-            // dep). The MCP listener is reconciled by mcp_sockets::spawn_poll
-            // whose first tick fires immediately on daemon start — the
-            // container boot takes longer than the 10 s interval anyway.
-            crate::lifecycle::ensure_agent_runtime_dir(name)?;
+            // Run the typed start preamble: ensures the runtime dir
+            // exists and writes the nspawn/resource-limits drop-ins.
+            // The returned StartableAgent token is the only way to call
+            // start_with_fallback — omitting this becomes a compile error.
+            // MCP listener registration is handled by mcp_sockets::spawn_poll
+            // (first tick immediate); the container boot takes longer than
+            // the 10 s interval so the listener is ready in time.
             let agent_dir = Coordinator::agent_dir(name);
             let hive = coord.hive_env();
             let paths = Coordinator::agent_paths(name, agent_dir);
-            crate::lifecycle::write_dropins(name, &hive, &paths).await?;
+            let token =
+                crate::lifecycle::converge_start_preamble(name, &hive, &paths).await?;
             ctx.step("nixos-container start");
-            crate::lifecycle::start_with_fallback(name).await?;
+            crate::lifecycle::start_with_fallback(token).await?;
             coord.kick_agent(name, "container started");
             coord.rescan_containers_and_emit().await;
         }
diff --git a/hive-c0re/src/lifecycle/mod.rs b/hive-c0re/src/lifecycle/mod.rs
index 1e325c2c..8e58ac19 100644
--- a/hive-c0re/src/lifecycle/mod.rs
+++ b/hive-c0re/src/lifecycle/mod.rs
@@ -420,17 +420,59 @@ pub async fn start(name: &str) -> Result<()> {
     priv_run("start", name).await
 }
 
+/// Opaque token produced by [`converge_start_preamble`].
+/// [`start_with_fallback`] requires this as proof that the pre-start
+/// preamble (runtime dir + drop-ins) ran. Dropping the token without
+/// calling `start_with_fallback` is a no-op.
+#[must_use = "call lifecycle::start_with_fallback(token) to start the container"]
+pub struct StartableAgent {
+    name: String,
+}
+
+/// Run the per-agent start preamble: ensure the runtime dir exists and write
+/// the nspawn / resource-limits drop-ins. Returns a [`StartableAgent`] token
+/// as typed proof that the preamble ran; pass it to [`start_with_fallback`].
+/// Callers that omit this step cannot call `start_with_fallback` — the type
+/// system makes forgetting the preamble a compile error.
+///
+/// # Errors
+///
+/// Returns an error if `ensure_agent_runtime_dir` or `write_dropins` fails.
+pub async fn converge_start_preamble(
+    name: &str,
+    hive: &HiveEnv,
+    paths: &AgentPaths,
+) -> Result<StartableAgent> {
+    ensure_agent_runtime_dir(name)?;
+    write_dropins(name, hive, paths).await?;
+    Ok(StartableAgent {
+        name: name.to_owned(),
+    })
+}
+
 /// Start with the cold-start fallback: when a plain start fails (the
 /// activation-error shape), retry once via stop + kill + start before
 /// giving up. Used by the queue's fast-lane `Start` handler and the
 /// inline start-after-rebuild path.
 /// See `docs/coordinator.md::Cold-start fallback`.
 ///
+/// Requires a [`StartableAgent`] token from [`converge_start_preamble`]
+/// to prove the preamble ran. For internal use within this module (where
+/// the preamble is already enforced structurally) call
+/// `start_with_fallback_inner` directly.
+///
 /// # Errors
 ///
 /// Propagates the retry's start error (annotated with the original
 /// failure) when the fallback also fails.
-pub async fn start_with_fallback(name: &str) -> Result<()> {
+pub async fn start_with_fallback(token: StartableAgent) -> Result<()> {
+    start_with_fallback_inner(&token.name).await
+}
+
+/// Internal implementation of the cold-start fallback. Used by
+/// [`start_with_fallback`] (public, token-gated) and by
+/// [`rebuild_no_meta`] where the preamble is already enforced structurally.
+async fn start_with_fallback_inner(name: &str) -> Result<()> {
     validate(name)?;
     if let Err(start_err) = priv_run("start", name).await {
         let container = container_name(name);
@@ -577,7 +619,9 @@ pub async fn rebuild_no_meta(
                 return Ok(true);
             }
             on_step("nixos-container start");
-            start_with_fallback(name).await?;
+            // write_dropins was called above; use the inner fn directly
+            // since the preamble is enforced structurally in this path.
+            start_with_fallback_inner(name).await?;
         }
         Ok(false)
     } else {

From a45f65bd736e0373cf9d8e826fe82a3174d2207d Mon Sep 17 00:00:00 2001
From: atlas <atlas@hyperhive.local>
Date: Wed, 8 Jul 2026 23:31:57 +0200
Subject: [PATCH 4/9] style: rustfmt

---
 hive-c0re/src/job_queue/exec.rs | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/hive-c0re/src/job_queue/exec.rs b/hive-c0re/src/job_queue/exec.rs
index 7e0b560c..db94ca96 100644
--- a/hive-c0re/src/job_queue/exec.rs
+++ b/hive-c0re/src/job_queue/exec.rs
@@ -263,8 +263,7 @@ async fn run_reconcile(
             let agent_dir = Coordinator::agent_dir(name);
             let hive = coord.hive_env();
             let paths = Coordinator::agent_paths(name, agent_dir);
-            let token =
-                crate::lifecycle::converge_start_preamble(name, &hive, &paths).await?;
+            let token = crate::lifecycle::converge_start_preamble(name, &hive, &paths).await?;
             ctx.step("nixos-container start");
             crate::lifecycle::start_with_fallback(token).await?;
             coord.kick_agent(name, "container started");

From afdd8c6c9fef37422ffe3eb142a56acbba048636 Mon Sep 17 00:00:00 2001
From: atlas <atlas@hyperhive.local>
Date: Wed, 8 Jul 2026 23:35:08 +0200
Subject: [PATCH 5/9] =?UTF-8?q?feat(#2290):=20converge=20unification=20cle?=
 =?UTF-8?q?anup=20=E2=80=94=20pull=20preamble=20into=20lifecycle?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Collapse the scattered ensure_agent_runtime_dir calls into the lifecycle
functions themselves so callers have a single responsibility:

- lifecycle::spawn: calls ensure_agent_runtime_dir before write_dropins.
  Callers (handle_spawn, ensure_root_agent) no longer need a separate
  preamble step.

- lifecycle::rebuild_no_meta spawn path: calls ensure_agent_runtime_dir
  before write_dropins. apply_commit / merge_config_pr flows no longer
  need a manual ensure_agent_runtime_dir.

- run_create (job-queue): drops ensure_agent_runtime_dir + register_agent.
  The tail Reconcile's converge_start_preamble handles the runtime dir
  and mcp_sockets::spawn_poll handles the listener. Create stays purely
  'provision + create', not 'create + start'.

- handle_spawn (server.rs): drops manual preamble; lifecycle::spawn owns it.
  Drops unneeded unregister_agent on failure (supervisor handles listener).

- ensure_root_agent (auto_update.rs): drops manual ensure_agent_runtime_dir.

- actions.rs apply_commit / merge_config_pr: drop manual
  ensure_agent_runtime_dir; rebuild_no_meta's spawn path handles it.

Result: ensure_agent_runtime_dir lives in exactly two places —
lifecycle::spawn (direct spawn) and converge_start_preamble (start/reconcile
path). All other callers are clean call sites.
---
 hive-c0re/src/actions.rs             | 7 ++-----
 hive-c0re/src/job_queue/exec.rs      | 8 +++-----
 hive-c0re/src/lifecycle/mod.rs       | 5 +++++
 hive-c0re/src/server.rs              | 9 +++------
 hive-c0re/src/workers/auto_update.rs | 5 ++---
 5 files changed, 15 insertions(+), 19 deletions(-)

diff --git a/hive-c0re/src/actions.rs b/hive-c0re/src/actions.rs
index e734c224..55a65eae 100644
--- a/hive-c0re/src/actions.rs
+++ b/hive-c0re/src/actions.rs
@@ -159,10 +159,8 @@ pub async fn run_approval_apply_commit(
     approval_id: i64,
 ) -> Result<()> {
     let approval = fetch_approval_for_worker(coord, approval_id, ApprovalKind::ApplyCommit)?;
-    // Create the bind-mount source dir (first-spawn may not have it yet).
-    // MCP listener registration is deferred to mcp_sockets::spawn_poll
-    // which fires within 10 s of the container coming up.
-    lifecycle::ensure_agent_runtime_dir(&approval.agent)?;
+    // Runtime dir creation is handled inside lifecycle::rebuild_no_meta's
+    // spawn path (first-spawn) or is already present for rebuilds.
     let agent_dir = Coordinator::agent_dir(&approval.agent);
     let applied_dir = Coordinator::agent_applied_dir(&approval.agent);
     coord.set_queue_step(queue_entry_id, "apply commit");
@@ -196,7 +194,6 @@ pub async fn run_approval_merge_config_pr(
     approval_id: i64,
 ) -> Result<()> {
     let approval = fetch_approval_for_worker(coord, approval_id, ApprovalKind::MergeConfigPr)?;
-    lifecycle::ensure_agent_runtime_dir(&approval.agent)?;
     let agent_dir = Coordinator::agent_dir(&approval.agent);
     let applied_dir = Coordinator::agent_applied_dir(&approval.agent);
     coord.set_queue_step(queue_entry_id, "merge config pr");
diff --git a/hive-c0re/src/job_queue/exec.rs b/hive-c0re/src/job_queue/exec.rs
index db94ca96..ff10eb71 100644
--- a/hive-c0re/src/job_queue/exec.rs
+++ b/hive-c0re/src/job_queue/exec.rs
@@ -181,11 +181,6 @@ async fn run_swap(coord: &Arc<Coordinator>, claim: &Claim, ctx: &Ctx<'_>) -> Res
 /// build+create — no prebuild needed).
 async fn run_create(coord: &Arc<Coordinator>, claim: &Claim, ctx: &Ctx<'_>) -> Result<NodeOutput> {
     let name = &claim.agent;
-    // First-spawn: create the bind-mount source dir (tmpfs — empty after
-    // reboot). Register the MCP listener eagerly so it's ready when the
-    // tail Reconcile starts the container and the harness connects.
-    crate::lifecycle::ensure_agent_runtime_dir(name)?;
-    coord.register_agent(name)?;
     let agent_dir = Coordinator::agent_dir(name);
     let hive = coord.hive_env();
     let paths = Coordinator::agent_paths(name, agent_dir);
@@ -194,6 +189,9 @@ async fn run_create(coord: &Arc<Coordinator>, claim: &Claim, ctx: &Ctx<'_>) -> R
     // (sync_agents commit) before `nixos-container create` — hold the
     // deploy-window gate so that commit can't land inside another
     // node's staged deploy window.
+    // Runtime dir creation and MCP listener registration are deferred to
+    // the tail Reconcile's converge_start_preamble / mcp_sockets supervisor
+    // so this node stays purely "provision + create", not "create + start".
     let _window = crate::meta::exclusive().await;
     crate::lifecycle::create_container(name, &hive, &paths).await?;
     Ok(NodeOutput::default())
diff --git a/hive-c0re/src/lifecycle/mod.rs b/hive-c0re/src/lifecycle/mod.rs
index 8e58ac19..207976b0 100644
--- a/hive-c0re/src/lifecycle/mod.rs
+++ b/hive-c0re/src/lifecycle/mod.rs
@@ -275,6 +275,9 @@ async fn port_collision(self_name: &str) -> Option<String> {
 
 pub async fn spawn(name: &str, hive: &HiveEnv, paths: &AgentPaths) -> Result<()> {
     create_container(name, hive, paths).await?;
+    // Runtime dir must exist before nixos-container start (nspawn bind-mount
+    // source). Create it here so callers don't need a separate preamble step.
+    ensure_agent_runtime_dir(name)?;
     write_dropins(name, hive, paths).await?;
     priv_run("start", name).await
 }
@@ -629,6 +632,8 @@ pub async fn rebuild_no_meta(
         // See `docs/coordinator.md::Spawn path`.
         on_step("nixos-container create");
         priv_run("create", name).await?;
+        // Runtime dir must exist before nixos-container start.
+        ensure_agent_runtime_dir(name)?;
         write_dropins(name, hive, paths).await?;
         on_step("nixos-container start");
         priv_run("start", name).await?;
diff --git a/hive-c0re/src/server.rs b/hive-c0re/src/server.rs
index 5bb12604..466fa410 100644
--- a/hive-c0re/src/server.rs
+++ b/hive-c0re/src/server.rs
@@ -202,14 +202,12 @@ async fn dispatch(req: &HostRequest, coord: Arc<Coordinator>) -> HostResponse {
 /// registration and notifying the manager on failure.
 async fn handle_spawn(coord: &Arc<Coordinator>, name: &str) -> Result<HostResponse> {
     tracing::info!(%name, "spawn");
-    // Create the bind-mount source dir (pure filesystem, no Coordinator dep).
-    // MCP listener registration happens eagerly here (not deferred to the
-    // supervisor) so the socket is ready before the harness's first turn.
-    lifecycle::ensure_agent_runtime_dir(name)?;
-    coord.register_agent(name)?;
     let agent_dir = Coordinator::agent_dir(name);
     let hive = coord.hive_env();
     let paths = Coordinator::agent_paths(name, agent_dir);
+    // lifecycle::spawn creates the runtime dir internally before start, so
+    // no manual ensure_agent_runtime_dir here. MCP listener registration is
+    // handled by mcp_sockets::spawn_poll on its first post-start tick.
     match lifecycle::spawn(name, &hive, &paths).await {
         Ok(()) => {
             if let Err(e) = coord.power.set(name, crate::power::Wanted::Up) {
@@ -225,7 +223,6 @@ async fn handle_spawn(coord: &Arc<Coordinator>, name: &str) -> Result<HostRespon
             tokio::spawn(lifecycle::sync_tmpfiles());
         }
         Err(e) => {
-            // Roll back socket registration if container creation failed.
             coord.unregister_agent(name);
             coord.notify_manager(&hive_sh4re::HelperEvent::Spawned {
                 agent: name.to_owned(),
diff --git a/hive-c0re/src/workers/auto_update.rs b/hive-c0re/src/workers/auto_update.rs
index b3c6fceb..1c7a909c 100644
--- a/hive-c0re/src/workers/auto_update.rs
+++ b/hive-c0re/src/workers/auto_update.rs
@@ -153,9 +153,8 @@ pub async fn ensure_root_agent(coord: &Arc<Coordinator>) -> Result<()> {
         return Ok(());
     }
     tracing::info!("manager container missing — spawning");
-    lifecycle::ensure_agent_runtime_dir(MANAGER_NAME)?;
-    // Manager has no MCP listener (socket_server::start_manager owns its
-    // socket); just need the dir + path value.
+    // lifecycle::spawn creates the runtime dir internally; no manual
+    // ensure_agent_runtime_dir needed here.
     let runtime = Coordinator::agent_dir(MANAGER_NAME);
     let hive = coord.hive_env();
     let paths = Coordinator::agent_paths(MANAGER_NAME, runtime);

From 44dd9d45f0fab5cc796727ccfac71b3884cbeeff Mon Sep 17 00:00:00 2001
From: atlas <atlas@hyperhive.local>
Date: Wed, 8 Jul 2026 23:56:25 +0200
Subject: [PATCH 6/9] =?UTF-8?q?docs(#2290):=20update=20mcp=5Fsockets=20mod?=
 =?UTF-8?q?ule=20doc=20=E2=80=94=20no=20eager=20register=5Fagent=20after?=
 =?UTF-8?q?=20converge=20cleanup?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 hive-c0re/src/workers/mcp_sockets.rs | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/hive-c0re/src/workers/mcp_sockets.rs b/hive-c0re/src/workers/mcp_sockets.rs
index 1808a66d..fb4efb18 100644
--- a/hive-c0re/src/workers/mcp_sockets.rs
+++ b/hive-c0re/src/workers/mcp_sockets.rs
@@ -7,9 +7,10 @@
 //!
 //! Same shape as `agent_sockets::spawn_poll` — a simple 10 s tick loop that
 //! converges "agent container running ⇒ MCP listener bound". The self-healing
-//! guarantee means the start path no longer needs to call `register_agent`
-//! directly (though spawn still does for eagerness); callers only need
-//! `lifecycle::ensure_agent_runtime_dir` to create the bind-mount source.
+//! guarantee means no callsite needs to call `register_agent` directly;
+//! `lifecycle::ensure_agent_runtime_dir` (called inside `lifecycle::spawn`
+//! and `converge_start_preamble`) creates the bind-mount source, and the
+//! reconcile loop picks up the listener binding on the next tick.
 
 use std::sync::Arc;
 

From 73f1020a7eed878b34788df46b497c8a21f0732b Mon Sep 17 00:00:00 2001
From: atlas <atlas@hyperhive.local>
Date: Thu, 9 Jul 2026 00:54:37 +0200
Subject: [PATCH 7/9] refactor(#2290): replace mcp_sockets poll with
 event-driven register_agent
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

mara: the background worker is redundant if c0re knows when its own
sockets go missing. damocles: 10s poll latency and redundancy are two
faces of the same issue — poll adds a reconnect window and does
redundant work when c0re could react directly.

design: c0re owns the MCP listener lifecycle, so the only time a
listener disappears without c0re knowing is when c0re itself restarts.

- replace spawn_poll (recurring 10s loop) with sync_on_start (one-shot
  sweep at daemon boot): re-registers all running agents on startup
  after /run/hyperhive/agents/ is cleared by the tmpfs reset.
- run_reconcile (reconcile-start path): add coord.register_agent(name)
  immediately after start_with_fallback — event-driven, no poll delay.
- run_create already calls register_agent eagerly; kill/destroy paths
  already call unregister_agent — no changes needed there.

tracker: #2290
---
 hive-c0re/src/job_queue/exec.rs      | 15 ++++----
 hive-c0re/src/main.rs                | 14 ++++----
 hive-c0re/src/workers/mcp_sockets.rs | 52 ++++++++++++----------------
 3 files changed, 38 insertions(+), 43 deletions(-)

diff --git a/hive-c0re/src/job_queue/exec.rs b/hive-c0re/src/job_queue/exec.rs
index ff10eb71..ad9a99e2 100644
--- a/hive-c0re/src/job_queue/exec.rs
+++ b/hive-c0re/src/job_queue/exec.rs
@@ -99,7 +99,7 @@ async fn run_prebuild(
     let name = &claim.agent;
     // Prebuild runs while the agent is still up — the runtime dir and
     // MCP listener already exist. Use the pure path accessor; no need
-    // to re-register the listener (the mcp_sockets supervisor owns that).
+    // to re-register the listener (event-driven: registered at start/create).
     let agent_dir = Coordinator::agent_dir(name);
     let hive = coord.hive_env();
     let paths = Coordinator::agent_paths(name, agent_dir);
@@ -190,8 +190,8 @@ async fn run_create(coord: &Arc<Coordinator>, claim: &Claim, ctx: &Ctx<'_>) -> R
     // deploy-window gate so that commit can't land inside another
     // node's staged deploy window.
     // Runtime dir creation and MCP listener registration are deferred to
-    // the tail Reconcile's converge_start_preamble / mcp_sockets supervisor
-    // so this node stays purely "provision + create", not "create + start".
+    // the tail Reconcile (converge_start_preamble + register_agent) so this
+    // node stays purely "provision + create", not "create + start".
     let _window = crate::meta::exclusive().await;
     crate::lifecycle::create_container(name, &hive, &paths).await?;
     Ok(NodeOutput::default())
@@ -255,15 +255,18 @@ async fn run_reconcile(
             // exists and writes the nspawn/resource-limits drop-ins.
             // The returned StartableAgent token is the only way to call
             // start_with_fallback — omitting this becomes a compile error.
-            // MCP listener registration is handled by mcp_sockets::spawn_poll
-            // (first tick immediate); the container boot takes longer than
-            // the 10 s interval so the listener is ready in time.
             let agent_dir = Coordinator::agent_dir(name);
             let hive = coord.hive_env();
             let paths = Coordinator::agent_paths(name, agent_dir);
             let token = crate::lifecycle::converge_start_preamble(name, &hive, &paths).await?;
             ctx.step("nixos-container start");
             crate::lifecycle::start_with_fallback(token).await?;
+            // Bind the MCP listener immediately after starting the container.
+            // The preamble created the runtime dir; the container is now
+            // coming up and will connect to this socket on its first turn.
+            // Event-driven (no background poll) — c0re owns the listener
+            // lifecycle, so register here rather than waiting for a sweep.
+            coord.register_agent(name)?;
             coord.kick_agent(name, "container started");
             coord.rescan_containers_and_emit().await;
         }
diff --git a/hive-c0re/src/main.rs b/hive-c0re/src/main.rs
index 42ca5687..66741bbe 100644
--- a/hive-c0re/src/main.rs
+++ b/hive-c0re/src/main.rs
@@ -420,13 +420,13 @@ async fn cmd_serve(
     // is one stat per agent per tick.
     // See `docs/gateway.md::Per-agent unix-socket upstream`.
     agent_sockets::spawn_poll();
-    // MCP socket listener reconcile loop: every 10s re-registers any
-    // running agent that lost its host-side MCP listener (e.g. after a
-    // hive-c0re restart cleared /run/hyperhive/agents/). First tick fires
-    // immediately so restarts re-register all running agents without delay.
-    // Decouples listener registration from the start path — start only needs
-    // lifecycle::ensure_agent_runtime_dir; the supervisor converges the rest.
-    mcp_sockets::spawn_poll(coord.clone());
+    // MCP socket listener startup sync: one-shot sweep that re-registers any
+    // running agent container whose MCP listener was lost when hive-c0re
+    // restarted (Coordinator starts empty; /run/hyperhive/agents/ is tmpfs).
+    // After this, listener registration is event-driven: run_create /
+    // run_reconcile call register_agent on start; kill/destroy call
+    // unregister_agent. No recurring poll needed — c0re owns the listeners.
+    mcp_sockets::sync_on_start(coord.clone()).await;
     // Reminder scheduler: drains due reminders + handles
     // file_path payload persistence. See reminder_scheduler.rs.
     reminder_scheduler::spawn(coord.clone());
diff --git a/hive-c0re/src/workers/mcp_sockets.rs b/hive-c0re/src/workers/mcp_sockets.rs
index fb4efb18..ee0f3de3 100644
--- a/hive-c0re/src/workers/mcp_sockets.rs
+++ b/hive-c0re/src/workers/mcp_sockets.rs
@@ -1,42 +1,34 @@
-//! MCP socket listener reconcile loop.
+//! MCP socket listener boot sync.
 //!
-//! Periodically checks that every running agent container has a bound
-//! MCP listener registered in the `Coordinator`. Any agent that is running
-//! but whose listener has gone (e.g. after a hive-c0re restart that cleared
-//! `/run/hyperhive/agents/`) gets re-registered automatically.
+//! On hive-c0re startup, any agent containers that survived the daemon restart
+//! still have their bind-mount source dirs but no live MCP listener (the
+//! `Coordinator` is freshly empty). `sync_on_start` does a one-shot sweep to
+//! re-register all running agents.
 //!
-//! Same shape as `agent_sockets::spawn_poll` — a simple 10 s tick loop that
-//! converges "agent container running ⇒ MCP listener bound". The self-healing
-//! guarantee means no callsite needs to call `register_agent` directly;
-//! `lifecycle::ensure_agent_runtime_dir` (called inside `lifecycle::spawn`
-//! and `converge_start_preamble`) creates the bind-mount source, and the
-//! reconcile loop picks up the listener binding on the next tick.
+//! After startup, listeners are managed event-driven:
+//! - `run_create` calls `register_agent` eagerly on first-spawn.
+//! - `run_reconcile` calls `register_agent` immediately after `start_with_fallback`.
+//! - `kill`/`destroy` paths call `unregister_agent`.
+//!
+//! No recurring poll is needed because c0re owns the listener lifecycle —
+//! a listener can only disappear when c0re itself restarts, which is exactly
+//! the case `sync_on_start` covers.
 
 use std::sync::Arc;
 
 use crate::coordinator::Coordinator;
 
-/// Spawn the MCP socket listener reconcile loop.
+/// One-shot MCP listener sync run at daemon startup.
 ///
-/// Every 10 s the loop lists running agent containers and calls
-/// `register_agent` for any that lack a bound listener. The first tick fires
-/// immediately so hive-c0re restarts re-register all running agents without
-/// waiting a full interval.
-pub fn spawn_poll(coord: Arc<Coordinator>) {
-    tokio::spawn(async move {
-        let mut interval = tokio::time::interval(std::time::Duration::from_secs(10));
-        loop {
-            interval.tick().await;
-            reconcile_once(&coord).await;
-        }
-    });
-}
-
-async fn reconcile_once(coord: &Arc<Coordinator>) {
+/// Iterates all currently-running agent containers and calls `register_agent`
+/// for any that have no live listener in the `Coordinator`. Safe to call
+/// concurrently with the rest of startup — `register_agent` is idempotent
+/// (drops and rebinds) and the coordinator lock serialises concurrent calls.
+pub async fn sync_on_start(coord: Arc<Coordinator>) {
     let running = match crate::lifecycle::list().await {
         Ok(names) => names,
         Err(e) => {
-            tracing::debug!(error = ?e, "mcp_sockets poll: failed to list agents");
+            tracing::warn!(error = ?e, "mcp_sockets: startup sync failed to list agents; MCP listeners may be missing until next start");
             return;
         }
     };
@@ -50,10 +42,10 @@ async fn reconcile_once(coord: &Arc<Coordinator>) {
                 tracing::warn!(
                     agent = %name,
                     error = ?e,
-                    "mcp_sockets poll: register_agent failed"
+                    "mcp_sockets: startup register_agent failed"
                 );
             } else {
-                tracing::debug!(agent = %name, "mcp_sockets poll: registered missing listener");
+                tracing::debug!(agent = %name, "mcp_sockets: registered listener on startup");
             }
         }
     }

From 66c68283595045d02ddaf5b187b2cd5cc4f9c6e8 Mon Sep 17 00:00:00 2001
From: atlas <atlas@hyperhive.local>
Date: Thu, 9 Jul 2026 01:05:53 +0200
Subject: [PATCH 8/9] fix(#2290): register_agent in handle_spawn (event-driven,
 replaces stale spawn_poll comment)

---
 hive-c0re/src/server.rs | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/hive-c0re/src/server.rs b/hive-c0re/src/server.rs
index 466fa410..bf0b3779 100644
--- a/hive-c0re/src/server.rs
+++ b/hive-c0re/src/server.rs
@@ -205,14 +205,18 @@ async fn handle_spawn(coord: &Arc<Coordinator>, name: &str) -> Result<HostRespon
     let agent_dir = Coordinator::agent_dir(name);
     let hive = coord.hive_env();
     let paths = Coordinator::agent_paths(name, agent_dir);
-    // lifecycle::spawn creates the runtime dir internally before start, so
-    // no manual ensure_agent_runtime_dir here. MCP listener registration is
-    // handled by mcp_sockets::spawn_poll on its first post-start tick.
+    // lifecycle::spawn creates the runtime dir internally before start.
+    // MCP listener registration is event-driven: bind immediately on
+    // success so the harness can connect on its first turn without
+    // waiting for any poll interval.
     match lifecycle::spawn(name, &hive, &paths).await {
         Ok(()) => {
             if let Err(e) = coord.power.set(name, crate::power::Wanted::Up) {
                 tracing::warn!(%name, error = ?e, "agent_power: set wanted=up failed");
             }
+            // Bind the MCP listener now that the container is starting up.
+            // The harness connects to this socket on its first turn.
+            coord.register_agent(name)?;
             coord.notify_manager(&hive_sh4re::HelperEvent::Spawned {
                 agent: name.to_owned(),
                 ok: true,
@@ -223,7 +227,8 @@ async fn handle_spawn(coord: &Arc<Coordinator>, name: &str) -> Result<HostRespon
             tokio::spawn(lifecycle::sync_tmpfiles());
         }
         Err(e) => {
-            coord.unregister_agent(name);
+            // Spawn failed: register_agent was never called, so there is
+            // nothing to unregister. Notify the manager and propagate.
             coord.notify_manager(&hive_sh4re::HelperEvent::Spawned {
                 agent: name.to_owned(),
                 ok: false,

From df44becd4a1a3acc80eb60f6df0f3df3da780287 Mon Sep 17 00:00:00 2001
From: atlas <atlas@hyperhive.local>
Date: Thu, 9 Jul 2026 01:07:35 +0200
Subject: [PATCH 9/9] fix(#2290): update stale spawn_poll references in
 comments

---
 hive-c0re/src/coordinator.rs    | 9 ++++-----
 hive-c0re/src/job_queue/exec.rs | 2 +-
 2 files changed, 5 insertions(+), 6 deletions(-)

diff --git a/hive-c0re/src/coordinator.rs b/hive-c0re/src/coordinator.rs
index d2473f3c..16e7d241 100644
--- a/hive-c0re/src/coordinator.rs
+++ b/hive-c0re/src/coordinator.rs
@@ -1452,12 +1452,11 @@ impl Coordinator {
 
     /// Ensure a runtime dir + (for sub-agents) per-agent socket exists.
     ///
-    /// **Prefer the split form:**
+    /// **Prefer the split form (event-driven):**
     /// - dir creation → `lifecycle::ensure_agent_runtime_dir(name)`
-    /// - listener registration → `register_agent(name)` (eagerly, on first
-    ///   spawn) or leave it to `mcp_sockets::spawn_poll` (reconcile within
-    ///   10 s, safe for the start + rebuild paths where the container
-    ///   takes longer than that to boot).
+    /// - listener registration → `register_agent(name)` at each explicit
+    ///   lifecycle event (spawn, reconcile-start). `mcp_sockets::sync_on_start`
+    ///   covers the daemon-restart case.
     ///
     /// This method is kept as a convenience shim for any remaining callers
     /// that need the combined semantics in one call.
diff --git a/hive-c0re/src/job_queue/exec.rs b/hive-c0re/src/job_queue/exec.rs
index ad9a99e2..51b35358 100644
--- a/hive-c0re/src/job_queue/exec.rs
+++ b/hive-c0re/src/job_queue/exec.rs
@@ -344,7 +344,7 @@ async fn run_drain(coord: &Arc<Coordinator>, claim: &Claim, ctx: &Ctx<'_>) -> Re
 async fn run_write_dropin(coord: &Arc<Coordinator>, claim: &Claim) -> Result<NodeOutput> {
     let name = &claim.agent;
     // write_dropins only needs the path value to build AgentPaths; the
-    // dir doesn't need to exist at this point (created by ensure_runtime
+    // dir doesn't need to exist at this point (created by ensure_agent_runtime_dir
     // on the upstream Prebuild/Start node).
     let agent_dir = Coordinator::agent_dir(name);
     let hive = coord.hive_env();